lukasz-antoniak commented on code in PR #2041: URL: https://github.com/apache/cassandra-java-driver/pull/2041#discussion_r2435396415
########## CONTRIBUTING.md: ########## @@ -17,518 +17,192 @@ specific language governing permissions and limitations under the License. --> -# Contributing guidelines +# Contributing Guidelines -## Code formatting +Thank you for your interest in contributing to the Apache Cassandra Java Driver! Please review the following guidelines to help you get started. -### Java +## Table of Contents -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. +- [Bugs, Features, and Questions](#bugs-features-and-questions) +- [Development Environment Setup](#development-environment-setup) +- [To Submit a Pull Request](#to-submit-a-pull-request) +- [Coding Guide](#coding-guide) -The build will fail if the code is not formatted. To format all files from the command line, run: - -``` -mvn fmt:format -``` +## Bugs, Features, and Questions -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. +- To report bugs or request features, please file a ticket on our [JIRA](https://issues.apache.org/jira/projects/CASSJAVA). +- For questions, use our [user mailing list](https://groups.google.com/a/lists.datastax.com/g/java-driver-user). -### XML +## Development Environment Setup -The build will fail if XML files are not formatted correctly. Run the following command before you -commit: +### Build and IDE Configuration -```java -mvn xml-format:xml-format -``` +- 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`. -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...). +### Running the Tests -### Other text files (markdown, etc) +#### Unit Tests -Similarly, enforce a right margin of 100 characters in those files. Editors and IDEs generally have -a way to configure this (for IDEA, install the "Wrap to column" plugin). +- Ensure you are using Java 8. +- Run: + ``` + mvn clean install -DskipTests + mvn test + ``` -## Coding style -- production code +#### Integration Tests + +1. Install Cassandra Cluster Manager (CCM) following its [README](https://github.com/apache/cassandra-ccm). +2. On macOS, 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: + ``` + mvn verify -Dccm.version=3.11.0 + ``` + +### Code Formatting and License Headers + +- We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). See [google-java-format](https://github.com/google/google-java-format) for IDE plugins. +- To format code: + ``` + # Java files + mvn fmt:format + # XML files + mvn xml-format:xml-format + # License headers + mvn license:format + ``` -Do not use static imports. They make things harder to understand when you look at the code -someplace where you don't have IDE support, like Github's code view. +### Pre-commit Hook (Highly Recommended) -Avoid abbreviations in class and variable names. A good rule of thumb is that you should only use -them if you would also do so verbally, for example "id" and "config" are probably reasonable. -Single-letter variables are permissible if the variable scope is only a few lines, or for commonly -understood cases (like `i` for a loop index). +- Make `pre-commit.sh` executable: + ``` + chmod +x pre-commit.sh + ``` +- Set up the pre-commit hook: + ``` + ln -s ../../pre-commit.sh .git/hooks/pre-commit + ``` +- This script will format files and run unit tests before each commit. -Keep source files short. Short files are easy to understand and test. The average should probably -be around 200-300 lines. +## To Submit a Pull Request +- Pull request titles must follow the format: `{JIRA-ticket-number}: {JIRA-ticket-title}` + Example: `CASSJAVA-40: Driver testing against Java 21` +- Before merging, squash your commits into a single commit with a message formatted as: + ``` + {JIRA-ticket-number}: {JIRA-ticket-title} + patch by {your-name}; reviewed by {approver-1} and {approver-2} for {JIRA-ticket-number} + ``` + +## Coding Guide ### Javadoc -All types in "API" packages must be documented. For "internal" packages, documentation is optional, -but in no way discouraged: it's generally a good idea to have a class-level comment that explains -where the component fits in the architecture, and anything else that you feel is important. +- **API packages:** must be documented. +- **Internal packages:** optional but encouraged—add a short class-level comment explaining the component’s role. -You don't need to document every parameter or return type, or even every method. Don't document -something if it is completely obvious, we don't want to end up with this: +You don’t need to document every method or parameter. Skip obvious stuff like: -```java +``` /** - * Returns the name. - * * @return the name */ String getName(); ``` - -On the other hand, there is often something useful to say about a method, so most should have at -least a one-line comment. Use common sense. - -Driver users coding in their IDE should find the right documentation at the right time. Try to -think of how they will come into contact with the class. For example, if a type is constructed with -a builder, each builder method should probably explain what the default is when you don't call it. - -Avoid using too many links, they can make comments harder to read, especially in the IDE. Link to a -type the first time it's mentioned, then use a text description ("this registry"...) or an `@code` -block. Don't link to a class in its own documentation. Don't link to types that appear right below -in the documented item's signature. - -```java -/** -* @return this {@link Builder} <-- completely unnecessary -*/ -Builder withLimit(int limit) { -``` - ### Logs +We use **SLF4J**: -We use SLF4J; loggers are declared like this: - -```java +``` private static final Logger LOG = LoggerFactory.getLogger(TheEnclosingClass.class); ``` -Logs are intended for two personae: - -* Ops who manage the application in production. -* Developers (maybe you) who debug a particular issue. - -The first 3 log levels are for ops: - -* `ERROR`: something that renders the driver -- or a part of it -- completely unusable. An action is - required to fix it: bouncing the client, applying a patch, etc. -* `WARN`: something that the driver can recover from automatically, but indicates a configuration or - programming error that should be addressed. For example: the driver connected successfully, but - one of the contact points in the configuration was malformed; the same prepared statement is being - prepared multiple time by the application code. -* `INFO`: something that is part of the normal operation of the driver, but might be useful to know - for an operator. For example: the driver has initialized successfully and is ready to process - queries; an optional dependency was detected in the classpath and activated an enhanced feature. - -Do not log errors that are rethrown to the client (such as the error that you're going to complete a -request with). This is annoying for ops because they see a lot of stack traces that require no -actual action on their part, because they're already handled by application code. +Logs help two groups: +1. **Ops** – running the app in production. +2. **Developers** – debugging issues. -Similarly, do not log stack traces for non-critical errors. If you still want the option to get the -trace for debugging, see the `Loggers.warnWithException` utility. +**Log levels:** -The last 2 levels are for developers, to help follow what the driver is doing from a "black box" -perspective (think about debugging an issue remotely, and all you have are the logs). +- **ERROR** – critical, needs action, not the ones re-thrown to the client +- **WARN** – recoverable but should be fixed. +- **INFO** – normal but useful events. +- **DEBUG** – detailed activity (e.g., state changes). +- **TRACE** – per-request details. -* `TRACE`: anything that happens **for every user request**. Not only request handling, but all - related components (e.g. timestamp generators, policies, etc). -* `DEBUG`: everything else. For example, node state changes, control connection activity, etc. +To change the log level when running tests, modify the `src/test/resources/logback-test.xml`. -Note that `DEBUG` and `TRACE` can coexist within the same component, for example the LBP -initializing is a one-time event, but returning a query plan is a per-request event. +**Log prefix** shows origin, e.g.: +`[s0|90232530|0]` (session name | hash code of the CqlRequestHandler instance | number of request attempts) -Logs statements start with a prefix that identifies its origin, for example: +### Integration Tests +Testing against an external process, using either of the tools: +- [Simulacron](https://github.com/datastax/simulacron): simulates Cassandra nodes on loopback. You “prime” it with expected query results. + *Example*: `NodeTargetingIT`. +- [CCM](https://github.com/pcmanus/ccm): launches actual Cassandra nodes locally. The `ccm` executable must be in the path. Pass variables like `-Dccm.version=5.0.0 -Dccm.dse=false` to specify the Cassandra version or distribution. Review Comment: Should be `-ccm.distribution=dse`. -- 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]
