From 8e551c7a5550c57a5434d5694988c6dd5e78960b Mon Sep 17 00:00:00 2001 From: Anush Date: Tue, 1 Oct 2024 14:18:18 +0530 Subject: [PATCH 1/3] docs: Updated CONTRIBUTING.md --- CONTRIBUTING.md | 123 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 82 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05b20cb..05abdd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,73 +52,114 @@ If you are modifying code, make sure it has no warnings when building. By contributing, you agree that your contributions will be licensed under its Apache License 2.0. -# Building the solution +# Contributing to Java client for Qdrant -The solution uses several open source software tools: +We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's: -## Docker +- Reporting a bug +- Discussing the current state of the code +- Submitting a fix +- Proposing new features -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. +## We Develop with GitHub -## Gradle +We use github to host code, to track issues and feature requests, as well as accept pull requests. -[Gradle](https://docs.gradle.org/current/userguide/userguide.html) is used as the build automation tool for the solution. -To get started after cloning the solution, it's best to run the gradlew wrapper script in the root +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. -for Windows +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. -``` -.\gradlew.bat build -``` +1. See if there is an existing issue +2. Fork the repo and create your branch from `master`. +3. If you've added code that should be tested, add tests. +4. Ensure the test suite passes. +5. Issue that pull request! -for OSX/Linux +## Report bugs using GitHub's [issues](https://github.com/qdrant/java-client/issues) -``` -./gradlew build -``` +We use GitHub issues to track public bugs. Report a bug by +[opening a new issue](https://github.com/qdrant/java-client/issues/new); it's that easy! -This will +**Great Bug Reports** tend to have: -- Pull down all the dependencies for the build process as well as the solution -- Run the default build task for the solution +- A quick summary and background +- Steps to reproduce + - Be specific! + - Give a sample code if you can. +- What you expected would happen +- What happens +- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) -You can also compile the solution within IntelliJ or other IDEs if you prefer. +## Coding Styleguide -## Tests +If you are modifying code, make sure it has no warnings when building. -jUnit5 tests are run as part of the default build task. These can also be run with +## License -``` -./gradlew test -``` +By contributing, you agree that your contributions will be licensed under its Apache License 2.0. -## Updating the client +## Preparing for a New Release -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 by `qdrantProtosVersion` in gradle.properties -in the root directory. +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). -When a new qdrant version is released upstream, update the `qdrantProtosVersion` value to the new version, -then run the build script +The generated files do not form part of the checked in source code. Instead, they are generated +and emitted into the `build/generated/source directory`, and included in compilation. -for Windows +### Pre-requisites -``` +Ensure the following are installed and available in the `PATH`. + +- [Java 17](https://www.azul.com/downloads/?version=java-17-lts&package=jdk#zulu) +- [Gradle](https://gradle.org/install/#with-a-package-manager). +- [Docker](https://docs.docker.com/engine/install/) for tests. + +### Steps + +1 - Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows: + +- `packageVersion` - Bump it to the next minor version to be released. +- `qdrantVersion` - Set it to `dev` to use the `dev` Docker image for testing. +- `qdrantProtosVersion` - Set it to `dev` to 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 Windows + +```bash .\gradlew.bat build ``` -for OSX/Linux +For OSX/Linux -``` +```bash ./gradlew build ``` -A specific version of the qdrant docker image can be targeted by modifying the `qdrantVersion` -in gradle.properties. +This will -The generated files do not form part of the checked in source code. Instead, they are generated -and emitted into the build/generated/source directory, and included in compilation. +- Pull down all the dependencies for the build process and the project. +- Run the default build task. +- Run the integration tests. Make sure to have Docker running. + +3 - Implement new Qdrant methods in [`QdrantClient.java`](https://github.com/qdrant/java-client/blob/master/src/main/java/io/qdrant/client/QdrantClient.java) with associated tests in [src/test](https://github.com/qdrant/java-client/tree/master/src/test/java/io/qdrant/client). + +Since the API reference is published at , the docstrings have to be appropriate. + +4 - If there are any new complex/frequently used properties in the proto definitions, add factory classes in [`src/main`](https://github.com/qdrant/java-client/tree/master/src/main/java/io/qdrant/client) following the existing patterns. + +4 - Submit your pull request and get those approvals. + +### Releasing a New Version + +Once the new Qdrant version is live: + +1 - Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows and build as mentioned above: + +- `qdrantVersion` - Set it to the released Docker image version for testing. +- `qdrantProtosVersion` - Set it to the released version of the Qdrant source for fetching the proto files. + +2 - Merge the pull request. -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. \ No newline at end of file +3 - Publish a new release at . The CI will then publish the library to [mvnrepository.com/artifact/io.qdrant/client](https://mvnrepository.com/artifact/io.qdrant/client) and the docs to . From fd5118947d36c2d18dc644689af9411a22c78d5d Mon Sep 17 00:00:00 2001 From: Anush Date: Tue, 1 Oct 2024 14:49:45 +0530 Subject: [PATCH 2/3] Update CONTRIBUTING.md --- CONTRIBUTING.md | 64 +++++++------------------------------------------ 1 file changed, 8 insertions(+), 56 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05abdd8..7d939cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,54 +52,6 @@ If you are modifying code, make sure it has no warnings when building. By contributing, you agree that your contributions will be licensed under its Apache License 2.0. -# Contributing to Java client for Qdrant - -We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's: - -- Reporting a bug -- Discussing the current state of the code -- Submitting a fix -- Proposing new features - -## 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 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. - -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 `master`. -3. If you've added code that should be tested, add tests. -4. Ensure the test suite passes. -5. Issue that pull request! - -## Report bugs using GitHub's [issues](https://github.com/qdrant/java-client/issues) - -We use GitHub issues to track public bugs. Report a bug by -[opening a new issue](https://github.com/qdrant/java-client/issues/new); it's that easy! - -**Great Bug Reports** tend to have: - -- A quick summary and background -- Steps to reproduce - - Be specific! - - Give a sample code if you can. -- What you expected would happen -- What happens -- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) - -## Coding Styleguide - -If you are modifying code, make sure it has no warnings when building. - -## License - -By contributing, you agree that your contributions will be licensed under its Apache License 2.0. - ## Preparing for a New Release 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). @@ -117,13 +69,13 @@ Ensure the following are installed and available in the `PATH`. ### Steps -1 - Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows: +1. Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows: - `packageVersion` - Bump it to the next minor version to be released. - `qdrantVersion` - Set it to `dev` to use the `dev` Docker image for testing. - `qdrantProtosVersion` - Set it to `dev` to 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: +2. Download and generate the latest client stubs by running the following command from the project root: For Windows @@ -143,23 +95,23 @@ This will - Run the default build task. - Run the integration tests. Make sure to have Docker running. -3 - Implement new Qdrant methods in [`QdrantClient.java`](https://github.com/qdrant/java-client/blob/master/src/main/java/io/qdrant/client/QdrantClient.java) with associated tests in [src/test](https://github.com/qdrant/java-client/tree/master/src/test/java/io/qdrant/client). +3. Implement new Qdrant methods in [`QdrantClient.java`](https://github.com/qdrant/java-client/blob/master/src/main/java/io/qdrant/client/QdrantClient.java) with associated tests in [src/test](https://github.com/qdrant/java-client/tree/master/src/test/java/io/qdrant/client). Since the API reference is published at , the docstrings have to be appropriate. -4 - If there are any new complex/frequently used properties in the proto definitions, add factory classes in [`src/main`](https://github.com/qdrant/java-client/tree/master/src/main/java/io/qdrant/client) following the existing patterns. +4. If there are any new complex/frequently used properties in the proto definitions, add factory classes in [`src/main`](https://github.com/qdrant/java-client/tree/master/src/main/java/io/qdrant/client) following the existing patterns. -4 - Submit your pull request and get those approvals. +5. Submit your pull request and get those approvals. ### Releasing a New Version Once the new Qdrant version is live: -1 - Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows and build as mentioned above: +1. Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows and build as mentioned above: - `qdrantVersion` - Set it to the released Docker image version for testing. - `qdrantProtosVersion` - Set it to the released version of the Qdrant source for fetching the proto files. -2 - Merge the pull request. +2. Merge the pull request. -3 - Publish a new release at . The CI will then publish the library to [mvnrepository.com/artifact/io.qdrant/client](https://mvnrepository.com/artifact/io.qdrant/client) and the docs to . +3. Publish a new release at . The CI will then publish the library to [mvnrepository.com/artifact/io.qdrant/client](https://mvnrepository.com/artifact/io.qdrant/client) and the docs to . From 5d67ebabe755fb5fe80dbc3ba864c80ec8a269c5 Mon Sep 17 00:00:00 2001 From: Anush Date: Thu, 10 Oct 2024 16:05:10 +0530 Subject: [PATCH 3/3] Review updates CONTRIBUTING.md --- CONTRIBUTING.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d939cd..2c420d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ By contributing, you agree that your contributions will be licensed under its Ap 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). -The generated files do not form part of the checked in source code. Instead, they are generated +The generated files do not form part of the checked-in source code. Instead, they are generated and emitted into the `build/generated/source directory`, and included in compilation. ### Pre-requisites @@ -67,6 +67,8 @@ Ensure the following are installed and available in the `PATH`. - [Gradle](https://gradle.org/install/#with-a-package-manager). - [Docker](https://docs.docker.com/engine/install/) for tests. +If you're using IntelliJ IDEA, see [this section](#intellij-idea) for steps to handle an IntelliSense issue. + ### Steps 1. Update the values in [gradle.properties](https://github.com/qdrant/java-client/blob/master/gradle.properties) as follows: @@ -93,7 +95,9 @@ This will - Pull down all the dependencies for the build process and the project. - Run the default build task. -- Run the integration tests. Make sure to have Docker running. +- Run the integration tests. Ensure Docker running. + +If a Qdrant image with static tags like `dev` or `latest` already exists on your system, the tests will use it. You can remove these images before running the tests to fetch the most up-to-date versions. 3. Implement new Qdrant methods in [`QdrantClient.java`](https://github.com/qdrant/java-client/blob/master/src/main/java/io/qdrant/client/QdrantClient.java) with associated tests in [src/test](https://github.com/qdrant/java-client/tree/master/src/test/java/io/qdrant/client). @@ -115,3 +119,17 @@ Once the new Qdrant version is live: 2. Merge the pull request. 3. Publish a new release at . The CI will then publish the library to [mvnrepository.com/artifact/io.qdrant/client](https://mvnrepository.com/artifact/io.qdrant/client) and the docs to . + +### IntelliJ IDEA + +If you're using [IntelliJ IDEA](https://www.jetbrains.com/idea/), IntelliSense may fail to work correctly due to large source files generated from proto-definitions. + +To resolve this, you can increase the file size limit by configuring IntelliJ IDEA as follows: + +1. In the top menu, navigate to `Help` -> `Edit Custom Properties`. + +2. Set the `idea.max.intellisense.filesize` properly to a higher value. + +![Screenshot 2024-10-02 at 11 13 06 PM](https://github.com/user-attachments/assets/7830d22c-4b63-4a03-8a8b-fbdd7acf3454) + +3. After saving the changes, restart the IDE to apply the new file size limit.