Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Added new version update instructions #69

Merged
merged 3 commits into from
Oct 10, 2024
Merged

docs: Added new version update instructions #69

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fdd7eed
docs: Added minor version update instructions
Anush008 Oct 1, 2024
b759cf3
Update CONTRIBUTING.md
Anush008 Oct 10, 2024
3c334be
--overwrite-protos flag
Anush008 Oct 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 51 additions & 66 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
```

Expand All @@ -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 `<QdrantVersion>` 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The build exe that this invokes only downloads files from a given <QdrantVersion> once

qdrant-dotnet/build/Main.cs

Lines 56 to 60 in e30739f

if (Directory.Exists(protosTagDir) && Directory.EnumerateFileSystemEntries(protosTagDir).Any())
{
Console.WriteLine($"Already downloaded protos for {qdrantVersion}");
return;
}

For a constantly changing upstream branch like dev, may want to either

  • introduce a command line argument to delete the downloaded proto files

or

  • introduce a convention to delete downloaded proto files for given <QdrantVersion>s

Copy link
Member Author

@Anush008 Anush008 Oct 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks.
Added a new flag.
3c334be (#69)

```
./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 `<QdrantVersion>` 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 `<QdrantVersion>` 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 `<QdrantVersion>` 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.