absurdfarce commented on code in PR #2041: URL: https://github.com/apache/cassandra-java-driver/pull/2041#discussion_r2886147153
########## 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 Review Comment: This Google Group is no longer a means of communication for this project. The Python and CPP drivers both point users at ASF Slack instead (see [here](https://github.com/apache/cassandra-python-driver/blob/trunk/README.rst?plain=1#L76-L79) as an example) and we should as well. It looks like the top-level README also [needs to get a similar update](https://github.com/apache/cassandra-java-driver/blob/4.x/README.md?plain=1#L79)... that's outside the scope of this PR and can be handled separately. ########## 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** Review Comment: We have a minimum Maven version that's supported for the project; probably need to explicitly include that here. CASSJAVA-102 bumped that minimum up to 3.8.1 at least for 4.x. ########## 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: IIRC this is a two-step process: 1. The user has to install a local version of the shaded Guava JAR into their Maven cache (which is what the command above does) 2. The user has to ignore the project in the "Maven" flyout window in the upper right (because we want them to fall back into the version that's now installed in their Maven cache). ########## 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: This raises an interesting point: the pre-reqs mentioned below apply to 4.x but are different for 3.x. I don't know that we need to enumerate a full set of separate requirements for 3.x distinct from those for 4.x but we probably should at least say (1) these reqs apply to 4.x and (2) 3.x may have different (and likely older) requirements. ########## 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: Out of curiosity... why not? If a user squashes commits on their PR branch and pushes what's the harm done? ########## 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** Review Comment: We've been asked this question a few times and in general our policy is a bit loose here. We don't _require_ a JIRA ticket for changes and I'm not sure I want to give the impression that that's a roadblock for users contributing code. We should certainly say that users are _encouraged_ to create a JIRA ticket describing the problem and perhaps including what they'd like to see done to fix it... and then follow that up with a PR. ########## 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: This is added here for... Simulacron testing, right? Might be worth calling that out explicitly. As it stands now this text appears to refer to something required for ccm testing which I don't think is correct. -- 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]
