There are many opportunities to contribute code to Apache Cassandra, including documentation updates, test improvements, bug fixes, changes to the Java code base, and tooling improvements.
Before getting started, please read Contributing to Cassandra, including the Code Changes, Code Style guidelines, testing, continuous integration and the code review checklist.
A recommended workflow to get started is:
- Find or create an issue in the Cassandra JIRA that describes the work you plan to do.
- Create a personal fork of the Apache Cassandra GitHub repo.
- Clone your fork into your development environment.
- Create your feature branch. Please see the branch naming suggestion, below.
- Make, build, test and self-review your changes on your feature branch. See 'Building and Testing' below.
- Push the branch to your fork and run it through a pre-commit CI, then attach the
resulting
ci_summaryandresults_detailsartefacts to the JIRA. See 'Continuous Integration' below. - Submit the patch, either by creating a GitHub pull request, attaching a patch file to your JIRA, or posting a link to a GitHub branch with your changes.
Branch naming: To ease collaboration, consider naming your feature branch like your-name/jira-id/base-branch. For
example, jcshepherd/CASSANDRA-12345/trunk. This convention will help with managing multiple collaborators on a shared
fork, and managing patches which differ across different Cassandra versions.
Note: Committers follow additional processes for handling patches, pull requests, and committing directly to the official repo, which the Apache Cassandra GitHub repo mirrors.
There are a number of Cassandra-related projects where contributions may be welcomed, including:
- Cassandra Website
- Cassandra Sidecar
- Cassandra Analytics
- Cassandra drivers for Java and Go
- Cassandra Spark Connector
- Cassandra DTests (distributed tests)
... and more. Visit those repositories and their related JIRA issues for more information on making contributions.
The scripts under .build/ build the project and run every kind of test, in docker or without it. CI runs these same scripts, so a test behaves the same on a laptop as it does in a pipeline. See .build/README.md, for example:
$ .build/docker/check-code.sh 17
$ .build/docker/run-tests.sh -a test -c 1/64
$ .build/docker/run-tests.sh -a jvm-dtest -t BooleanTest
Guidelines on what and how to test are in TESTING.md, and on the website.
Three separate systems test the project. Knowing which one applies saves time.
GitHub Actions run ant check (licence and checkstyle checks) against JDK 11 and JDK 17 on every push to any branch of any fork. See .github/workflows/.
Pre-commit CI runs the test pipeline against a branch, before the patch is committed. It is driven from a checkout with .build/run-ci, or via the Jenkins UI, and it needs a Jenkins to run on: pre-ci.cassandra.apache.org for community volunteers, donated to the project by Amazon; a clone your employer operates; or one you provision yourself in any Kubernetes cluster with .build/run-ci --only-setup.
# push the branch first, then
$ .build/run-ci --profile pre-commit --url pre-ci.cassandra.apache.org --user myuser
The run leaves build/ci/ci_summary_*.html and build/ci/results_details_*.tar.xz behind; attach both to the JIRA ticket. Every patch is expected to carry them, and a contributor without access to any CI system should say so on the ticket, so a committer can run it for them.
Post-commit CI at ci-cassandra.apache.org runs the full pipeline against trunk and the release branches after every merge. It never tests uncommitted patches; results are archived at nightlies.apache.org and tracked over time by Butler.
The full process is documented at cassandra.apache.org. In-tree: .build/run-ci.d/README.md for every option of the script, and .jenkins/k8s/README.md for provisioning an instance of your own.
Apache Cassandra uses git submodules for a set of dependencies, this is to make cross cutting changes easier for developers. When working on such changes, there are a set of scripts to help with the process.
When starting a development branch, the following will change all submodules to a new branch based off the JIRA
$ .build/sh/development-switch.sh --jira CASSANDRA-<number>
When changes are made to a submodule (such as to accord), you need to commit and update the reference in Apache Cassandra
$ (cd modules/accord ; git commit -am 'Saving progress')
$ .build/sh/bump-accord.sh
Due to the nature of submodules, the changes to the submodules must be committed and pushed before the changes to Apache Cassandra; these are different repositories so git's --atomic does not prevent conflicts from concurrent merges; the basic process is as follows:
- Follow the normal merge process for the submodule
- Update Apache Cassandra's submodule entry to point to the newly committed change; follow the Accord example below for an example
$ .build/sh/change-submodule-accord.sh
$ .build/sh/bump-accord.sh