From fdd7eed4ac588773a53546ea7e4a0d020bc110f6 Mon Sep 17 00:00:00 2001 From: Anush Date: Tue, 1 Oct 2024 15:19:39 +0530 Subject: [PATCH 1/3] docs: Added minor version update instructions --- CONTRIBUTING.md | 117 +++++++++++++++++++++--------------------------- 1 file changed, 51 insertions(+), 66 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3250b16..164007e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,29 +9,29 @@ We love your input! We want to make contributing to this project as easy and tra ## We Develop with GitHub -We use github to host code, to track issues and feature requests, as well as accept pull requests. +We use GitHub to host code, to track issues and feature requests, as well as accept pull requests. We Use [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow), so all code changes -happen through Pull Requests. Pull requests are the best way to propose changes to the codebase. +happen through Pull Requests. Pull requests are the best way to propose changes to the codebase. -It's usually best to open an issue first to discuss a feature or bug before opening a pull request. +It's usually best to open an issue first to discuss a feature or bug before opening a pull request. Doing so can save time and help further ascertain the crux of an issue. 1. See if there is an existing issue 2. Fork the repo and create your branch from `main`. -2. If you've added code that should be tested, add tests. -3. Ensure the test suite passes. -4. Issue that pull request! +3. If you've added code that should be tested, add tests. +4. Ensure the test suite passes. +5. Issue that pull request! ### Any contributions you make will be under the Apache License 2.0 -In short, when you submit code changes, your submissions are understood to be under the +In short, when you submit code changes, your submissions are understood to be under the same [Apache License 2.0](https://choosealicense.com/licenses/apache-2.0/) that covers the project. Feel free to contact the maintainers if that's a concern. ## Report bugs using GitHub's [issues](https://github.com/qdrant/qdrant-dotnet/issues) -We use GitHub issues to track public bugs. Report a bug by +We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/qdrant/qdrant-dotnet/issues/new); it's that easy! **Great Bug Reports** tend to have: @@ -47,10 +47,10 @@ We use GitHub issues to track public bugs. Report a bug by ## Coding Styleguide If you are modifying code, make sure it has no warnings when building. -The project uses [dotnet format](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format) formatter in +The project uses [dotnet format](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format) formatter in conjunction with rules defined in .editorconfig file. Please ensure to run it using -``` +```bash ./build.sh format ``` @@ -60,89 +60,74 @@ before submitting a PR. By contributing, you agree that your contributions will be licensed under its Apache License 2.0. -# Building the solution +## Preparing for a New Release -The solution uses several open source software tools: +The client uses generated stubs from upstream Qdrant proto definitions, which are downloaded from [qdrant/qdrant](https://github.com/qdrant/qdrant/tree/master/lib/api/src/grpc/proto). -## Docker +The generated files do not form part of the checked in source code. Instead, they are generated +and emitted into the `src/Qdrant.Client/obj/Release`, and included in compilation. -Qdrant docker image is used to run integration tests. Be sure to -[install docker](https://docs.docker.com/engine/install/) and have it running when running tests. +### Pre-requisites -## Bullseye +Ensure the following are installed and available in the `PATH`. -[Bullseye](https://github.com/adamralph/bullseye) is used as the build automation system for the solution. -To get started after cloning the solution, it's best to run the build script in the root +- [Dotnet 6.0.x](https://dotnet.microsoft.com/download/dotnet/6.0) +- [Docker](https://docs.docker.com/engine/install/) for tests -for Windows +### Steps -``` -.\build.bat -``` +1. Set the `` value in [Directory.Build.props](https://github.com/qdrant/qdrant-dotnet/blob/main/Directory.Build.props) to `dev`. In order to download the `dev` Docker image for testing and use the `dev` branch for fetching the proto files. + +2. Download and generate the latest client stubs by running the following command from the project root: -for OSX/Linux +For Windows +```bash +.\build.bat build ``` -./build.sh + +For OSX/Linux + +```bash +./build.sh build ``` This will -- Pull down all the dependencies for the build process as well as the solution -- Run the default build target for the solution +- Pull down all the dependencies for the build process and the project. +- Run the format and default build task. -You can also compile the solution within Visual Studio or Rider if you prefer, but the build script is -going to be _much_ faster. +For testing, ensure Docker is running and run the following command. -## Tests +```bash +.\build.bat test +``` -xUnit tests are run as part of the default build target. These can also be run with +For OSX/Linux -``` +```bash ./build.sh test ``` -## Updating the client +3. Implement new Qdrant methods in [`QdrantClient.cs`](https://github.com/qdrant/qdrant-dotnet/blob/main/src/Qdrant.Client/QdrantClient.cs) with associated tests in [tests/Qdrant.Client.Tests/](https://github.com/qdrant/qdrant-dotnet/tree/main/tests/Qdrant.Client.Tests). -A large portion of the client is generated from the upstream qdrant proto definitions, which are -downloaded locally as needed, based on the version defined in `` in Directory.Build.props -in the root directory. +4. If there are any new complex/frequently used properties in the proto definitions, add implicit converters to [`src/Qdrant.Client/Grpc`](https://github.com/qdrant/qdrant-dotnet/tree/main/src/Qdrant.Client/Grpc) following the existing patterns. -When a new qdrant version is released upstream, update the `` value to the new version, -then run the build script +5. Submit your pull request and get those approvals. -for Windows +### Releasing a New Version -``` -.\build.bat -``` +Once the new Qdrant version is live: -for OSX/Linux +1. Set the `` value in [Directory.Build.props](https://github.com/qdrant/qdrant-dotnet/blob/main/Directory.Build.props) to the released Qdrant version. For eg: `v1.13.0`. -``` -./build.sh -``` +2. Merge the pull request. -The generated files do not form part of the checked in source code. Instead, they are generated -and emitted into the respective Target Framework Moniker (TFM) directory in the given -Configuration directory in the Qdrant.Client `obj` directory. For example, a Release build of -net6.0 emits generated files to `src/Qdrant.Client/obj/Release/net6.0`, and these generated -files are included in compilation. +3. [MinVer](https://github.com/adamralph/minver) is used for versioning the package using Git tags. To create a new release -If upstream changes to proto definitions change the API of generated code, you may need -to fix compilation errors in code that relies on that generated code. - -## MinVer - -[MinVer](https://github.com/adamralph/minver) is used for versioning projects and packages using -Git tags. To create a new release - -1. Create a new tag and push it to origin +```bash +git tag 1.6.0 +git push --tags +``` - ``` - git tag 1.6.0 - git push --tags - ``` - -2. Create a new release on GitHub from the tag. -3. The CI uploads a NuGet package artifact after the release. +4. Create a new release on GitHub from the tag. The CI will upload a NuGet package artifact after the release. From b759cf35a797ad8f3e47d65a8a1db32a985439aa Mon Sep 17 00:00:00 2001 From: Anush Date: Thu, 10 Oct 2024 10:42:07 +0530 Subject: [PATCH 2/3] Update CONTRIBUTING.md Co-authored-by: Russ Cam --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 164007e..a570a57 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,7 +71,7 @@ and emitted into the `src/Qdrant.Client/obj/Release`, and included in compilatio Ensure the following are installed and available in the `PATH`. -- [Dotnet 6.0.x](https://dotnet.microsoft.com/download/dotnet/6.0) +- [Dotnet 8.0.x](https://dotnet.microsoft.com/download/dotnet/8.0) - [Docker](https://docs.docker.com/engine/install/) for tests ### Steps From 3c334becde7d6246f2b0dee151252ad99f06cb6d Mon Sep 17 00:00:00 2001 From: Anush008 Date: Thu, 10 Oct 2024 16:30:34 +0530 Subject: [PATCH 3/3] --overwrite-protos flag --- CONTRIBUTING.md | 4 ++-- build/Main.cs | 24 ++++++++++++++++++++---- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a570a57..54d1d19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,13 +83,13 @@ Ensure the following are installed and available in the `PATH`. For Windows ```bash -.\build.bat build +.\build.bat build --overwrite-protos ``` For OSX/Linux ```bash -./build.sh build +./build.sh build --overwrite-protos ``` This will diff --git a/build/Main.cs b/build/Main.cs index 585d5c2..0796188 100644 --- a/build/Main.cs +++ b/build/Main.cs @@ -1,5 +1,5 @@ -using System.Collections.Generic; using System.CommandLine; +using System.CommandLine.Invocation; using System.IO.Compression; using System.Net.Http.Headers; using System.Text.RegularExpressions; @@ -19,6 +19,12 @@ var qdrantVersion = doc.Descendants(XName.Get("QdrantVersion", "http://schemas.microsoft.com/developer/msbuild/2003")) .First().Value; +var overwriteProtosOption = new Option( + ["--overwrite-protos", "-o"], + () => false, + "Overwrite already downloaded Proto files." +); + var cmd = new RootCommand { new Argument("targets") @@ -26,16 +32,18 @@ Description = "A list of targets to run or list. If not specified, the \"default\" target will be run, or all targets will be listed.", }, + overwriteProtosOption }; foreach (var (aliases, description) in Options.Definitions) cmd.Add(new Option(aliases.ToArray(), description)); -cmd.SetHandler(async () => +cmd.SetHandler(async (InvocationContext context) => { // translate from System.CommandLine to Bullseye var cmdLine = cmd.Parse(args); var targets = cmdLine.CommandResult.Tokens.Select(token => token.Value); + var overwriteProtos = context.ParseResult.GetValueForOption(overwriteProtosOption); var options = new Options(Options.Definitions.Select(d => (d.Aliases[0], cmdLine.GetValueForOption(cmd.Options.OfType>().Single(o => o.HasAlias(d.Aliases[0])))))); @@ -55,8 +63,16 @@ var protosTagDir = Path.Combine(protosDir, qdrantVersion); if (Directory.Exists(protosTagDir) && Directory.EnumerateFileSystemEntries(protosTagDir).Any()) { - Console.WriteLine($"Already downloaded protos for {qdrantVersion}"); - return; + if (!overwriteProtos) + { + Console.WriteLine($"Already downloaded protos for {qdrantVersion}"); + return; + } + else + { + Console.WriteLine($"Overwriting existing protos for {qdrantVersion}"); + Directory.Delete(protosTagDir, true); + } } Directory.CreateDirectory(protosTagDir);