Contributing to Cassandra
|
Preview | Unofficial | For review only |
Apache Cassandra is an open-source project that welcomes contributions of all kinds: code, documentation, tests, bug reports, and tooling improvements. Whether you are fixing your first bug or implementing a major feature, this section provides everything you need to contribute effectively.
|
Do this first
|
You can read and run tests while the ICLA is processing, but you cannot merge patches until it is approved.
Find Your Path
Not sure where to start? The Contributor Roadmap helps you choose the right path based on what you want to do: fix a bug, add a feature, learn the codebase, write tests, improve documentation, or review patches.
Learn the Codebase
Cassandra is a large distributed systems codebase. These resources make it legible:
-
Cassandra Internals Map — every major subsystem mapped to source packages, key classes, and cross-subsystem boundaries
-
Query Execution Path — trace a CQL query from client to disk and back
-
Messaging and Failure Handling — how nodes communicate and detect failures
-
SSTable Architecture — deep dive into the storage engine, from the SSTable book
Sections
- Get Oriented
-
Contributor Roadmap — find the right starting path for your contribution goals.
Cassandra Internals Map — a subsystem-by-subsystem map of the codebase.
Subsystem Expert Discovery — who reviews what, and how to find the right people. - Learn the Codebase
-
Architecture Overview — Cassandra internals: the Dynamo-inspired storage engine, consistent hashing, and the Accord consensus protocol.
Query Execution Path — follow a CQL request through coordinator, replica, and storage layers.
Messaging and Failure Handling — internode communication, gossip, and failure detection. - SSTable Architecture
-
SSTable Fundamentals — what SSTables are, component anatomy, format evolution.
Write Path: CQL to Disk — the full mutation pipeline from CQL to flushed SSTable.
SSTable Data Format — on-disk encoding for partitions, rows, cells, and collections.
Read Path: Lookups and Indexes — Bloom filters, indexes, and how reads find data.
Compaction and Tombstone Lifecycle — compaction strategies, tombstone reconciliation, repair, and backups.
SSTable Reference — versioning matrix, encoding cheat sheet, tools, and glossary. - Build and Validate
-
Build and Test Overview — clone the repository, build from source, set up your IDE, and run the test suites.
Test Selection Matrix — which tests to run for which kind of change.
Debugging Locally — debug unit tests, dtests, and reproduce CI failures.
Profiling and Performance Validation — CPU profiling, benchmarks, and regression detection. - Develop Features
-
Feature Development Playbook — end-to-end guide from scoping to submission.
Patch Classification Guide — expectations per patch type: tests, docs, reviewers.
Compatibility and Upgrade Checklist — pre-submission checks for protocol, config, and format changes.
Operational Empathy Checklist — connecting code changes to operator consequences. - Submit and Review
-
Patches and Review Overview — the contribution workflow from JIRA ticket to committed patch.
Code Style — formatting and style conventions.
Review Checklist — what reviewers look for.
AI-Assisted Contribution Policy — rules for AI-generated code and docs.
Working with Agentic Coding Tools — using Claude Code, Cursor, and Copilot with Cassandra. - Release and Docs
-
Release and Publish Overview — CI infrastructure, dependency management, and the release process.
Working on Documentation — how Cassandra docs are structured and how to submit documentation patches.
Generated Documentation — how reference pages forcassandra.yaml, nodetool, and the native protocol are generated from source. - Good First Contributions
-
Contribution Ladder — stepped entry points from first bug fix to cross-cutting feature.
First Deep Contribution Walkthrough — a worked example tying together the internals map, test selection, and review process.