Operators Developers Contributors Reference
Sidebar updates per section — preview limitation
Apache Cassandra

Contributing Code Changes

This page describes the workflow for contributing code to Apache Cassandra. It is grounded in the project’s CONTRIBUTING.md.

What You Can Contribute

Contributions include bug fixes, Java code changes, tooling improvements (Java or Python), documentation updates, and test improvements.

As a general rule:

  • Major new features require discussion on the dev@cassandra.apache.org">dev mailing list before implementation

  • Bug fixes take higher priority than features

  • Test requirements scale with the risk of your change — storage engine changes need more tests than tooling changes

  • Smaller, focused patches are faster to review — consider breaking large issues into smaller tasks

Looking for a first contribution? Browse issues tagged low hanging fruit in JIRA.

Before You Start Coding

  1. Search JIRA for existing issues at issues.apache.org/jira/browse/CASSANDRA to avoid redundant work

  2. If you have not used ASF JIRA before, read JIRA quickstart first.

  3. Create a JIRA ticket early describing what you plan to do — not just after finishing

  4. Get feedback on the dev mailing list or JIRA, especially for features or major changes

  5. Link related JIRA issues to provide context

  6. Update your ticket periodically with progress and link to your work-in-progress branch

Contribution Workflow

The recommended workflow from CONTRIBUTING.md:

  1. Find or create a JIRA ticket describing the work

  2. Fork apache/cassandra on GitHub

  3. Clone your fork:

    git clone https://github.com/<your-username>/cassandra.git
cd cassandra
git remote add upstream https://github.com/apache/cassandra.git

  4. Create a feature branch:

    git checkout -b <your-name>/CASSANDRA-<number>/trunk
    The naming convention your-name/jira-id/base-branch (e.g., jsmith/CASSANDRA-12345/trunk) helps manage collaboration on shared forks and patches across Cassandra versions.

  5. Initialize submodules if not already done:

    git submodule update --init --recursive

  6. Build, test, and self-review your changes

  7. Submit: prefer a GitHub pull request for active review; attach a patch to JIRA only when the workflow or reviewer asks for it

Working with Submodules

Apache Cassandra uses git submodules for dependencies such as Accord. When making cross-cutting changes that touch submodules:

Start a Development Branch

.build/sh/development-switch.sh --jira CASSANDRA-<number>

This creates matching branches across submodules.

Commit Submodule Changes

When you modify a submodule (e.g., Accord):

(cd modules/accord ; git commit -am 'Saving progress')
.build/sh/bump-accord.sh

Merge Order for Submodules

Submodule changes must be committed and pushed before the main Cassandra changes because they are separate repositories. The basic process:

  1. Follow the normal merge process for the submodule

  2. Update Cassandra’s submodule entry:

    .build/sh/change-submodule-accord.sh
.build/sh/bump-accord.sh

Choosing the Right Branch

Create your patch against the appropriate branch. Bug fixes should target the earliest affected release branch. Merge order is always from older to newer:

cassandra-4.1 -> cassandra-5.0 -> trunk

New features should target trunk unless there is a specific reason to target a release branch.

Creating a Patch

  1. Verify your changes follow the code style

  2. Ensure tests pass (see Testing)

  3. Walk through the review checklist for your own code

  4. Squash commits into a clean history — multiple commits are fine during review, but squash before final merge

  5. If you need to combine local commits before sending a patch, use git rebase -i HEAD~N and keep the final history reviewable.

  6. Include a CHANGES.txt entry at the top of the list

  7. Put the entry in the unreleased section at the top of CHANGES.txt and write it from the user’s perspective.

    # Good CHANGES.txt entries
- nodetool getlogginglevels output is sorted alphabetically (CASSANDRA-12345)
- Accord migration now preserves read availability during phase changes (CASSANDRA-67890)

# Bad CHANGES.txt entries
- Replaced HashMap with TreeMap in GetLoggingLevels.java (CASSANDRA-12345)
- Fixed some internals

  8. Format commit messages as:

    <One sentence description>

patch by <Author>; reviewed by <Reviewer> for CASSANDRA-#####

  9. Submit via GitHub pull request or attach a patch file to JIRA, depending on the review path you are using

  10. Click Submit Patch on the JIRA ticket to move it to Patch Available, which tells reviewers the patch is ready

  11. Wait for review and a +1 — iterate on feedback as needed

Do not delete your branches immediately after they are committed. Keep them available in case a merge issue requires access to the original code.

Related Projects

Contributions are also welcomed to other Cassandra-related projects, including: