absurdfarce commented on code in PR #2041: URL: https://github.com/apache/cassandra-java-driver/pull/2041#discussion_r2986238279
########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) + - [Don't abuse the stream API](#dont-abuse-the-stream-api) + - [Never assume a specific format for toString()](#never-assume-a-specific-format-for-tostring) + - [Concurrency annotations](#concurrency-annotations) + - [Nullability annotations](#nullability-annotations) +- [Coding Guidelines for Tests](#coding-guidelines-for-tests) + - [Coding style -- test code](#coding-style----test-code) + - [Unit tests](#unit-tests) + - [Integration tests](#integration-tests) -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See -https://github.com/google/google-java-format for IDE plugins. The rules are not configurable. +## Ways to Contribute -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +There are many ways to contribute, including: -Some aspects are not covered by the formatter: braces must be used with `if`, `else`, `for`, `do` -and `while` statements, even when the body is empty or contains only a single statement. +- **Bug Reports**: Identify incorrect behavior, inconsistencies, or regressions in the driver. Provide reproduction steps when possible. +- **Feature Requests**: Propose improvements or new functionality. Please describe the use case (not just a proposed API). +- **Documentation Improvements**: Enhance guides, examples, javadocs, or configuration explanations. +- **Pull Requests**: Submit fixes, enhancements, performance improvements, or refactorings. +- **Testing Contributions**: Add missing tests, improve coverage, or enhance test infrastructure. +- **Support & Triage**: Help evaluate reported issues or contribute to discussions. +- **Verify Releases**: Verify the release artifacts work correctly in your environment, when a release is proposed in the mailing list. -### XML +### Communication +1. **Mailing List**: https://groups.google.com/a/lists.datastax.com/g/java-driver-user +2. **JIRA**: https://issues.apache.org/jira/projects/CASSJAVA +3. **GitHub Repository**: https://github.com/apache/cassandra-java-driver +4. **Slack**: #cassandar-drivers channel, if you are in the Apache Software Foundation [Slack](https://infra.apache.org/slack.html) -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: -```java -mvn xml-format:xml-format +## Contribution Process + +### Reporting Issues + +All issues must be tracked in **Apache JIRA**: +<https://issues.apache.org/jira/projects/CASSJAVA> + +When filing an issue: + +- Clearly describe the problem, expected behavior, and actual behavior. +- Include driver version, Java version, and Cassandra cluster details. +- Add reproduction steps or a minimal test case if possible. +- Use the appropriate issue type (Bug, Improvement, New Feature, etc.). +- Set the correct components (e.g., `core`, `mapper-runtime`, `quarkus`). + +Committers will help refine the ticket if needed. + +### Submitting Changes (Pull Requests) + +All code changes require: + +1. **A corresponding JIRA ticket** + Include the JIRA key in the PR title, e.g.: + `CASSJAVA-40: Driver testing against Java 21` + +2. **A pull request on GitHub** + Repository: <https://github.com/apache/cassandra-java-driver> + +3. **Tests** + Every fix or feature should include or update tests. PRs without tests are rarely accepted. + +4. **Documentation updates** + Update manual, javadocs, examples, or reference docs when applicable. + +5. **Passing CI** + PRs must pass all CI jobs unless reviewers explicitly allow exceptions. + +**Do not** mix unrelated changes in one PR—keep contributions focused. + +**Do not** base a PR on another one. + +**Do not** squash commits before the PR is ready to merge. + +--- + +## Development Setup + +### Prerequisites + +- **Java 8+** +- **Maven** + +### Building the Project + +- Ensure Maven is installed and you are using Java 8. +- Build the project with: + ``` + mvn clean package -DskipTests + ``` +- If using an IDE like IntelliJ and encountering issues with guava-shaded classes: + - Run: + ``` + mvn clean install -DskipTests + ``` + - If IntelliJ uses a different Maven version, use the Maven window in IntelliJ: under `Lifecycle`, click `clean` and then `install`. Review Comment: Hmmmm, that was very definitely _not_ adequate for me... but I'm fine rolling with this for now. We can deal with it on a case-by-case basis via Slack and update this if it becomes a problem (which I doubt it will). ########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) + - [Don't abuse the stream API](#dont-abuse-the-stream-api) + - [Never assume a specific format for toString()](#never-assume-a-specific-format-for-tostring) + - [Concurrency annotations](#concurrency-annotations) + - [Nullability annotations](#nullability-annotations) +- [Coding Guidelines for Tests](#coding-guidelines-for-tests) + - [Coding style -- test code](#coding-style----test-code) + - [Unit tests](#unit-tests) + - [Integration tests](#integration-tests) -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See -https://github.com/google/google-java-format for IDE plugins. The rules are not configurable. +## Ways to Contribute -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +There are many ways to contribute, including: -Some aspects are not covered by the formatter: braces must be used with `if`, `else`, `for`, `do` -and `while` statements, even when the body is empty or contains only a single statement. +- **Bug Reports**: Identify incorrect behavior, inconsistencies, or regressions in the driver. Provide reproduction steps when possible. +- **Feature Requests**: Propose improvements or new functionality. Please describe the use case (not just a proposed API). +- **Documentation Improvements**: Enhance guides, examples, javadocs, or configuration explanations. +- **Pull Requests**: Submit fixes, enhancements, performance improvements, or refactorings. +- **Testing Contributions**: Add missing tests, improve coverage, or enhance test infrastructure. +- **Support & Triage**: Help evaluate reported issues or contribute to discussions. +- **Verify Releases**: Verify the release artifacts work correctly in your environment, when a release is proposed in the mailing list. -### XML +### Communication +1. **Mailing List**: https://groups.google.com/a/lists.datastax.com/g/java-driver-user +2. **JIRA**: https://issues.apache.org/jira/projects/CASSJAVA +3. **GitHub Repository**: https://github.com/apache/cassandra-java-driver +4. **Slack**: #cassandar-drivers channel, if you are in the Apache Software Foundation [Slack](https://infra.apache.org/slack.html) -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: -```java -mvn xml-format:xml-format +## Contribution Process + +### Reporting Issues + +All issues must be tracked in **Apache JIRA**: +<https://issues.apache.org/jira/projects/CASSJAVA> + +When filing an issue: + +- Clearly describe the problem, expected behavior, and actual behavior. +- Include driver version, Java version, and Cassandra cluster details. +- Add reproduction steps or a minimal test case if possible. +- Use the appropriate issue type (Bug, Improvement, New Feature, etc.). +- Set the correct components (e.g., `core`, `mapper-runtime`, `quarkus`). + +Committers will help refine the ticket if needed. + +### Submitting Changes (Pull Requests) + +All code changes require: + +1. **A corresponding JIRA ticket** + Include the JIRA key in the PR title, e.g.: + `CASSJAVA-40: Driver testing against Java 21` + +2. **A pull request on GitHub** + Repository: <https://github.com/apache/cassandra-java-driver> + +3. **Tests** + Every fix or feature should include or update tests. PRs without tests are rarely accepted. + +4. **Documentation updates** + Update manual, javadocs, examples, or reference docs when applicable. + +5. **Passing CI** + PRs must pass all CI jobs unless reviewers explicitly allow exceptions. + +**Do not** mix unrelated changes in one PR—keep contributions focused. + +**Do not** base a PR on another one. + +**Do not** squash commits before the PR is ready to merge. + +--- + +## Development Setup + +### Prerequisites + +- **Java 8+** +- **Maven** + +### Building the Project + +- Ensure Maven is installed and you are using Java 8. +- Build the project with: + ``` + mvn clean package -DskipTests + ``` +- If using an IDE like IntelliJ and encountering issues with guava-shaded classes: + - Run: + ``` + mvn clean install -DskipTests + ``` + - If IntelliJ uses a different Maven version, use the Maven window in IntelliJ: under `Lifecycle`, click `clean` and then `install`. + +### Running Tests + +#### Unit Tests + +```bash +mvn clean install -DskipTests +mvn test ``` -The formatter does not enforce a maximum line length, but please try to keep it below 100 characters -to keep files readable across all mediums (IDE, terminal, Github...). +#### Integration Tests + +1. Install Cassandra Cluster Manager (CCM) following its [README](https://github.com/apache/cassandra-ccm). +2. On MacOS only, enable loopback aliases: Review Comment: I don't have personal knowledge of the requirement; I don't run any of this on OS X. I'm just going by what the [original CONTRIBUTING doc said](https://github.com/apache/cassandra-java-driver/blob/4.19.2/CONTRIBUTING.md?plain=1#L269-L275) on the topic. ########## CONTRIBUTING.md: ########## @@ -371,164 +493,11 @@ public TestRule chain = RuleChain.outerRule(ccmRule).around(sessionRule); Only use this for: -* CCM tests that use `@CassandraRequirement` or `@DseRequirement` restrictions at the method level +* CCM tests that use `@BackendRequirement` restrictions at the method level (ex: `BatchStatementIT`). * tests where you *really* need to restart from a clean state for every method. ##### Mixed It's also possible to use a `@ClassRule` for CCM / Simulacron, and a `@Rule` for the session rule. In that case, you don't need to use a rule chain. - -## Running the tests - -### Unit tests - - mvn clean test - -This currently takes about 30 seconds. The goal is to keep it within a couple of minutes (it runs -for each commit if you enable the pre-commit hook -- see below). - -### Integration tests - - mvn clean verify - -This currently takes about 9 minutes. We don't have a hard limit, but ideally it should stay within -30 minutes to 1 hour. - -You can skip test categories individually with `-DskipParallelizableITs`, `-DskipSerialITs` and -`-DskipIsolatedITs` (`-DskipITs` still works to skip them all at once). - -### Configuring MacOS for Simulacron - -Simulacron (used in integration tests) relies on loopback aliases to simulate multiple nodes. On -Linux or Windows, you shouldn't have anything to do. On MacOS, run this script: - -``` -#!/bin/bash -for sub in {0..4}; do - echo "Opening for 127.0.$sub" - for i in {0..255}; do sudo ifconfig lo0 alias 127.0.$sub.$i up; done -done -``` - -Note that this is known to cause temporary increased CPU usage in OS X initially while mDNSResponder -acclimates itself to the presence of added IP addresses. This lasts several minutes. Also, this does -not survive reboots. - - -## License headers - -The build will fail if some license headers are missing. To update all files from the command line, -run: - -``` -mvn license:format -``` - -## Pre-commit hook (highly recommended) - -Ensure `pre-commit.sh` is executable, then run: - -``` -ln -s ../../pre-commit.sh .git/hooks/pre-commit -``` - -This will only allow commits if the tests pass. It is also a good reminder to keep the test suite -short. - -Note: the tests run on the current state of the working directory. I tried to add a `git stash` in -the script to only test what's actually being committed, but I couldn't get it to run reliably -(it's still in there but commented). Keep this in mind when you commit, and don't forget to re-add -the changes if the first attempt failed and you fixed the tests. - -## Speeding up the build for local tests - -If you need to install something in your local repository quickly, you can use the `fast` profile to -skip all "non-essential" checks (licenses, formatting, tests, etc): - -``` -mvn clean install -Pfast -``` - -You can speed things up even more by targeting specific modules with the `-pl` option: - -``` -mvn clean install -Pfast -pl core,query-builder,mapper-runtime,mapper-processor,bom -``` - -Please run the normal build at least once before you push your changes. - -## Commits - -Keep your changes **focused**. Each commit should have a single, clear purpose expressed in its -message. - -Resist the urge to "fix" cosmetic issues (add/remove blank lines, move methods, etc.) in existing -code. This adds cognitive load for reviewers, who have to figure out which changes are relevant to -the actual issue. If you see legitimate issues, like typos, address them in a separate commit (it's -fine to group multiple typo fixes in a single commit). - -Isolate trivial refactorings into separate commits. For example, a method rename that affects dozens -of call sites can be reviewed in a few seconds, but if it's part of a larger diff it gets mixed up -with more complex changes (that might affect the same lines), and reviewers have to check every -line. - -Commit message subjects start with a capital letter, use the imperative form and do **not** end -with a period: - -* correct: "Add test for CQL request handler" -* incorrect: "~~Added test for CQL request handler~~" -* incorrect: "~~New test for CQL request handler~~" - -Avoid catch-all messages like "Minor cleanup", "Various fixes", etc. They don't provide any useful -information to reviewers, and might be a sign that your commit contains unrelated changes. - -We don't enforce a particular subject line length limit, but try to keep it short. - -You can add more details after the subject line, separated by a blank line. The following pattern -(inspired by [Netty](http://netty.io/wiki/writing-a-commit-message.html)) is not mandatory, but -welcome for complex changes: - -``` -One line description of your change - -Motivation: - -Explain here the context, and why you're making that change. -What is the problem you're trying to solve. - -Modifications: - -Describe the modifications you've done. - -Result: - -After your change, what will change. -``` - -## Pull requests - -Like commits, pull requests should be focused on a single, clearly stated goal. - -Don't base a pull request onto another one, it's too complicated to follow two branches that evolve -at the same time. If a ticket depends on another, wait for the first one to be merged. - -If you have to address feedback, avoid rewriting the history (e.g. squashing or amending commits): -this makes the reviewers' job harder, because they have to re-read the full diff and figure out -where your new changes are. Instead, push a new commit on top of the existing history; it will be -squashed later when the PR gets merged. If the history is complex, it's a good idea to indicate in -the message where the changes should be squashed: Review Comment: Interesting that we used to have this instruction in the CONTRIBUTING doc. It obviously doesn't apply anymore now that we've moved away from squash merges... but it _does_ suggest to me that this might be a good place to provide instructions to a user about how do a squash via an interactive rebase. We _can_ do that for user-contributed PRs but I'd kind of prefer to put that on the contributors if we can. ########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) + - [Don't abuse the stream API](#dont-abuse-the-stream-api) + - [Never assume a specific format for toString()](#never-assume-a-specific-format-for-tostring) + - [Concurrency annotations](#concurrency-annotations) + - [Nullability annotations](#nullability-annotations) +- [Coding Guidelines for Tests](#coding-guidelines-for-tests) + - [Coding style -- test code](#coding-style----test-code) + - [Unit tests](#unit-tests) + - [Integration tests](#integration-tests) -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See -https://github.com/google/google-java-format for IDE plugins. The rules are not configurable. +## Ways to Contribute -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +There are many ways to contribute, including: -Some aspects are not covered by the formatter: braces must be used with `if`, `else`, `for`, `do` -and `while` statements, even when the body is empty or contains only a single statement. +- **Bug Reports**: Identify incorrect behavior, inconsistencies, or regressions in the driver. Provide reproduction steps when possible. +- **Feature Requests**: Propose improvements or new functionality. Please describe the use case (not just a proposed API). +- **Documentation Improvements**: Enhance guides, examples, javadocs, or configuration explanations. +- **Pull Requests**: Submit fixes, enhancements, performance improvements, or refactorings. +- **Testing Contributions**: Add missing tests, improve coverage, or enhance test infrastructure. +- **Support & Triage**: Help evaluate reported issues or contribute to discussions. +- **Verify Releases**: Verify the release artifacts work correctly in your environment, when a release is proposed in the mailing list. -### XML +### Communication +1. **Mailing List**: https://groups.google.com/a/lists.datastax.com/g/java-driver-user +2. **JIRA**: https://issues.apache.org/jira/projects/CASSJAVA +3. **GitHub Repository**: https://github.com/apache/cassandra-java-driver +4. **Slack**: #cassandar-drivers channel, if you are in the Apache Software Foundation [Slack](https://infra.apache.org/slack.html) -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: -```java -mvn xml-format:xml-format +## Contribution Process + +### Reporting Issues + +All issues must be tracked in **Apache JIRA**: +<https://issues.apache.org/jira/projects/CASSJAVA> + +When filing an issue: + +- Clearly describe the problem, expected behavior, and actual behavior. +- Include driver version, Java version, and Cassandra cluster details. +- Add reproduction steps or a minimal test case if possible. +- Use the appropriate issue type (Bug, Improvement, New Feature, etc.). +- Set the correct components (e.g., `core`, `mapper-runtime`, `quarkus`). + +Committers will help refine the ticket if needed. + +### Submitting Changes (Pull Requests) + +All code changes require: + +1. **A corresponding JIRA ticket** + Include the JIRA key in the PR title, e.g.: + `CASSJAVA-40: Driver testing against Java 21` + +2. **A pull request on GitHub** + Repository: <https://github.com/apache/cassandra-java-driver> + +3. **Tests** + Every fix or feature should include or update tests. PRs without tests are rarely accepted. + +4. **Documentation updates** + Update manual, javadocs, examples, or reference docs when applicable. + +5. **Passing CI** + PRs must pass all CI jobs unless reviewers explicitly allow exceptions. + +**Do not** mix unrelated changes in one PR—keep contributions focused. + +**Do not** base a PR on another one. + +**Do not** squash commits before the PR is ready to merge. + +--- + +## Development Setup + +### Prerequisites Review Comment: Ah, entirely fair point... we can ignore this one! ########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) + - [Don't abuse the stream API](#dont-abuse-the-stream-api) + - [Never assume a specific format for toString()](#never-assume-a-specific-format-for-tostring) + - [Concurrency annotations](#concurrency-annotations) + - [Nullability annotations](#nullability-annotations) +- [Coding Guidelines for Tests](#coding-guidelines-for-tests) + - [Coding style -- test code](#coding-style----test-code) + - [Unit tests](#unit-tests) + - [Integration tests](#integration-tests) -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See -https://github.com/google/google-java-format for IDE plugins. The rules are not configurable. +## Ways to Contribute -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +There are many ways to contribute, including: -Some aspects are not covered by the formatter: braces must be used with `if`, `else`, `for`, `do` -and `while` statements, even when the body is empty or contains only a single statement. +- **Bug Reports**: Identify incorrect behavior, inconsistencies, or regressions in the driver. Provide reproduction steps when possible. +- **Feature Requests**: Propose improvements or new functionality. Please describe the use case (not just a proposed API). +- **Documentation Improvements**: Enhance guides, examples, javadocs, or configuration explanations. +- **Pull Requests**: Submit fixes, enhancements, performance improvements, or refactorings. +- **Testing Contributions**: Add missing tests, improve coverage, or enhance test infrastructure. +- **Support & Triage**: Help evaluate reported issues or contribute to discussions. +- **Verify Releases**: Verify the release artifacts work correctly in your environment, when a release is proposed in the mailing list. -### XML +### Communication +1. **Mailing Lists**: Mail to [email protected] or [email protected] to join the [email protected] or [email protected] mailing lists. +2. **Slack**: #cassandar-drivers channel in the Apache Software Foundation [Slack](https://infra.apache.org/slack.html). You can ask for an invite to the ASF Slack workspace in the mailing lists. +3. **JIRA**: https://issues.apache.org/jira/projects/CASSJAVA +4. **GitHub Repository**: https://github.com/apache/cassandra-java-driver -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: -```java -mvn xml-format:xml-format +## Contribution Process + +### Reporting Issues + +All issues must be tracked in **Apache JIRA**: +<https://issues.apache.org/jira/projects/CASSJAVA> + +When filing an issue: + +- Clearly describe the problem, expected behavior, and actual behavior. +- Include driver version, Java version, and Cassandra cluster details. +- Add reproduction steps or a minimal test case if possible. +- Use the appropriate issue type (Bug, Improvement, New Feature, etc.). +- Set the correct components (e.g., `core`, `mapper-runtime`, `quarkus`). + +Committers will help refine the ticket if needed. + +### Submitting Changes (Pull Requests) + +All code changes require: + +1. **A corresponding JIRA ticket** unless it's a ninja fix. + Include the JIRA key in the PR title, e.g.: + `CASSJAVA-40: Driver testing against Java 21` + +2. **A pull request on GitHub** + Repository: <https://github.com/apache/cassandra-java-driver> + +3. **Tests** + Every fix or feature should include or update tests. PRs without tests are rarely accepted. + +4. **Documentation updates** + Update manual, javadocs, examples, or reference docs when applicable. + +5. **Passing CI** + PRs must pass all CI jobs unless reviewers explicitly allow exceptions. + +**Do not** mix unrelated changes in one PR—keep contributions focused. + +**Do not** base a PR on another one. + +**Do not** squash commits before the PR is ready to merge. + +--- + +## Development Setup + +### Prerequisites + +- **Java 8+** +- **Maven 3.8.1+** + +### Building the Project + +- Ensure Maven is installed and you are using Java 8. +- Build the project with: + ``` + mvn clean package -DskipTests + ``` +- If using an IDE like IntelliJ and encountering issues with guava-shaded classes: + - Run: + ``` + mvn clean install -DskipTests + ``` + - If IntelliJ uses a different Maven version, use the Maven window in IntelliJ: under `Lifecycle`, click `clean` and then `install`. + +### Running Tests + +#### Unit Tests + +```bash +mvn clean install -DskipTests Review Comment: This used to be required because of the need to have the shaded Guava JAR in place when compiling tests IIRC... I think I've still seen that behaviour fairly recently. ########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) + - [Don't abuse the stream API](#dont-abuse-the-stream-api) + - [Never assume a specific format for toString()](#never-assume-a-specific-format-for-tostring) + - [Concurrency annotations](#concurrency-annotations) + - [Nullability annotations](#nullability-annotations) +- [Coding Guidelines for Tests](#coding-guidelines-for-tests) + - [Coding style -- test code](#coding-style----test-code) + - [Unit tests](#unit-tests) + - [Integration tests](#integration-tests) -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See -https://github.com/google/google-java-format for IDE plugins. The rules are not configurable. +## Ways to Contribute -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +There are many ways to contribute, including: -Some aspects are not covered by the formatter: braces must be used with `if`, `else`, `for`, `do` -and `while` statements, even when the body is empty or contains only a single statement. +- **Bug Reports**: Identify incorrect behavior, inconsistencies, or regressions in the driver. Provide reproduction steps when possible. +- **Feature Requests**: Propose improvements or new functionality. Please describe the use case (not just a proposed API). +- **Documentation Improvements**: Enhance guides, examples, javadocs, or configuration explanations. +- **Pull Requests**: Submit fixes, enhancements, performance improvements, or refactorings. +- **Testing Contributions**: Add missing tests, improve coverage, or enhance test infrastructure. +- **Support & Triage**: Help evaluate reported issues or contribute to discussions. +- **Verify Releases**: Verify the release artifacts work correctly in your environment, when a release is proposed in the mailing list. -### XML +### Communication +1. **Mailing List**: https://groups.google.com/a/lists.datastax.com/g/java-driver-user +2. **JIRA**: https://issues.apache.org/jira/projects/CASSJAVA +3. **GitHub Repository**: https://github.com/apache/cassandra-java-driver +4. **Slack**: #cassandar-drivers channel, if you are in the Apache Software Foundation [Slack](https://infra.apache.org/slack.html) -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: -```java -mvn xml-format:xml-format +## Contribution Process + +### Reporting Issues + +All issues must be tracked in **Apache JIRA**: +<https://issues.apache.org/jira/projects/CASSJAVA> + +When filing an issue: + +- Clearly describe the problem, expected behavior, and actual behavior. +- Include driver version, Java version, and Cassandra cluster details. +- Add reproduction steps or a minimal test case if possible. +- Use the appropriate issue type (Bug, Improvement, New Feature, etc.). +- Set the correct components (e.g., `core`, `mapper-runtime`, `quarkus`). + +Committers will help refine the ticket if needed. + +### Submitting Changes (Pull Requests) + +All code changes require: + +1. **A corresponding JIRA ticket** + Include the JIRA key in the PR title, e.g.: + `CASSJAVA-40: Driver testing against Java 21` + +2. **A pull request on GitHub** + Repository: <https://github.com/apache/cassandra-java-driver> + +3. **Tests** + Every fix or feature should include or update tests. PRs without tests are rarely accepted. + +4. **Documentation updates** + Update manual, javadocs, examples, or reference docs when applicable. + +5. **Passing CI** + PRs must pass all CI jobs unless reviewers explicitly allow exceptions. + +**Do not** mix unrelated changes in one PR—keep contributions focused. + +**Do not** base a PR on another one. + +**Do not** squash commits before the PR is ready to merge. Review Comment: I guess I don't see this as a huge problem but agree it doesn't hurt anything to prohibit it in the general case. ########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) Review Comment: 👍 I very much agree that "Logging" is a better description for that section. ########## CONTRIBUTING.md: ########## @@ -17,42 +17,154 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing to the Cassandra Java Driver -## Code formatting +Thank you for your interest in contributing! -### Java +## Table of Contents +- [Ways to Contribute](#ways-to-contribute) +- [Contribution Process](#contribution-process) + - [Reporting Issues](#reporting-issues) + - [Submitting Changes (Pull Requests)](#submitting-changes-pull-requests) +- [Development Setup](#development-setup) + - [Prerequisites](#prerequisites) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) +- [Coding Guidelines](#coding-guidelines) + - [General](#general) + - [Code Formatting and License Headers](#code-formatting-and-license-headers) + - [Javadoc](#javadoc) + - [Logging](#logging) + - [Don't abuse the stream API](#dont-abuse-the-stream-api) + - [Never assume a specific format for toString()](#never-assume-a-specific-format-for-tostring) + - [Concurrency annotations](#concurrency-annotations) + - [Nullability annotations](#nullability-annotations) +- [Coding Guidelines for Tests](#coding-guidelines-for-tests) + - [Coding style -- test code](#coding-style----test-code) + - [Unit tests](#unit-tests) + - [Integration tests](#integration-tests) -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See -https://github.com/google/google-java-format for IDE plugins. The rules are not configurable. +## Ways to Contribute -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +There are many ways to contribute, including: -Some aspects are not covered by the formatter: braces must be used with `if`, `else`, `for`, `do` -and `while` statements, even when the body is empty or contains only a single statement. +- **Bug Reports**: Identify incorrect behavior, inconsistencies, or regressions in the driver. Provide reproduction steps when possible. +- **Feature Requests**: Propose improvements or new functionality. Please describe the use case (not just a proposed API). +- **Documentation Improvements**: Enhance guides, examples, javadocs, or configuration explanations. +- **Pull Requests**: Submit fixes, enhancements, performance improvements, or refactorings. +- **Testing Contributions**: Add missing tests, improve coverage, or enhance test infrastructure. +- **Support & Triage**: Help evaluate reported issues or contribute to discussions. +- **Verify Releases**: Verify the release artifacts work correctly in your environment, when a release is proposed in the mailing list. -### XML +### Communication +1. **Mailing Lists**: Mail to [email protected] or [email protected] to join the [email protected] or [email protected] mailing lists. +2. **Slack**: #cassandar-drivers channel in the Apache Software Foundation [Slack](https://infra.apache.org/slack.html). You can ask for an invite to the ASF Slack workspace in the mailing lists. +3. **JIRA**: https://issues.apache.org/jira/projects/CASSJAVA +4. **GitHub Repository**: https://github.com/apache/cassandra-java-driver -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: -```java -mvn xml-format:xml-format +## Contribution Process + +### Reporting Issues + +All issues must be tracked in **Apache JIRA**: +<https://issues.apache.org/jira/projects/CASSJAVA> + +When filing an issue: + +- Clearly describe the problem, expected behavior, and actual behavior. +- Include driver version, Java version, and Cassandra cluster details. +- Add reproduction steps or a minimal test case if possible. +- Use the appropriate issue type (Bug, Improvement, New Feature, etc.). +- Set the correct components (e.g., `core`, `mapper-runtime`, `quarkus`). + +Committers will help refine the ticket if needed. + +### Submitting Changes (Pull Requests) + +All code changes require: + +1. **A corresponding JIRA ticket** unless it's a ninja fix. + Include the JIRA key in the PR title, e.g.: + `CASSJAVA-40: Driver testing against Java 21` + +2. **A pull request on GitHub** + Repository: <https://github.com/apache/cassandra-java-driver> + +3. **Tests** + Every fix or feature should include or update tests. PRs without tests are rarely accepted. + +4. **Documentation updates** + Update manual, javadocs, examples, or reference docs when applicable. + +5. **Passing CI** + PRs must pass all CI jobs unless reviewers explicitly allow exceptions. + +**Do not** mix unrelated changes in one PR—keep contributions focused. + +**Do not** base a PR on another one. + +**Do not** squash commits before the PR is ready to merge. + +--- + +## Development Setup + +### Prerequisites + +- **Java 8+** +- **Maven 3.8.1+** + +### Building the Project + +- Ensure Maven is installed and you are using Java 8. +- Build the project with: + ``` + mvn clean package -DskipTests + ``` +- If using an IDE like IntelliJ and encountering issues with guava-shaded classes: + - Run: + ``` + mvn clean install -DskipTests + ``` + - If IntelliJ uses a different Maven version, use the Maven window in IntelliJ: under `Lifecycle`, click `clean` and then `install`. + +### Running Tests + +#### Unit Tests + +```bash +mvn clean install -DskipTests +mvn test ``` -The formatter does not enforce a maximum line length, but please try to keep it below 100 characters -to keep files readable across all mediums (IDE, terminal, Github...). +#### Integration Tests + +1. Install Cassandra Cluster Manager (CCM) following its [README](https://github.com/apache/cassandra-ccm). +2. On MacOS only, enable loopback aliases: + +```shell +for i in {2..255}; do sudo ifconfig lo0 alias 127.0.0.$i up; done + ``` + Note: This may slow down networking. To remove the aliases after testing: + ```shell + for i in {2..255}; do sudo ifconfig lo0 -alias 127.0.0.$i up; done + ``` +3. Run integration tests: + ``` + mvn clean verify + ``` + To target a specific Cassandra version or distribution: + ``` + mvn verify -Dccm.version=3.11.0 Review Comment: It's meant as an example here for the user; presumably they'd tweak it for their own use case when they actually run it. There's certainly no _harm_ in bumping this up to a newer version but even using 3.11.0 seems to illustrate the point well enough. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
