Writing a new feature is just one way to contribute to the Cassandra project. In fact, making sure that supporting tasks, such as quality testing, documentation, and helping users are completed is just as important. Tracking the development of new features is an ongoing challenge for this project, like most open source projects. We suggest learning how this project gets things done before tackling a new feature. Here are some suggestions for ways to contribute:

The Cassandra documentation is maintained in the Cassandra source repository along with the Cassandra code base. To submit changes to the documentation, follow the standard process for submitting a patch.

Subscribe to the user list, look for some questions you can answer and write a reply. Simple as that! See the community page for details on how to subscribe to the mailing list.

Reviewing patches is not the sole domain of committers. If others review a patch, it can reduce the load on the committers. Less time spent reviewing patches means committers can more great features or review more complex patches. Follow the instructions in How to review or alternatively, create a build with the patch and test it with your own workload. Add a comment to the JIRA ticket to let others know you’ve reviewed and tested, along with the results of your work. For example:

Often, the hardest work in fixing a bug is reproducing it. Even if youdon’t have the knowledge to produce a fix, figuring out a way to reliably reproduce an issue can be a massive contribution. Document your method of reproduction in a JIRA comment or, better yet, produce an automated test that reproduces the issue and attach it to the ticket. If you go as far as producing a fix, follow the process for submitting a patch.

To create a JIRA account, please request it on the #cassandra or #cassandra-dev channels on ASF Slack, or on the user or dev mailing list.

Test coverage for Cassandra will always benefit from more automated test coverage, as with most code bases. Before starting work on a particular area of code, consider reviewing and enhancing the existing test coverage. You’ll both improve your knowledge of the code before you start on an enhancement, and reduce the chance introducing issues with your change. See testing and patches for more detail.

Building Cassandra from source is the first important step in contributing to the Apache Cassandra project. You will need to install Java (JDK 8 or 11, depending on which version you want to build Cassandra against, best is to install both and then switch between them when needed), Git, and Ant (including ant-optional).

The source code for Cassandra is shared on the central Apache Git repository and organized by branch, one branch for each major version. You can access the code for the current development branch at gitbox.apache.org/repos/asf/cassandra.git (the primary location) or at github.com/apache/cassandra (a mirror location).

However, to develop a patch or a new feature, you should fork the Cassandra project first and then clone it from your own fork:

Cassandra is a Java project which is built using Ant. The build file, build.xml located in the root of the project content, has various tasks defined (you can list all of them with some short descriptions by running ant -p).

The build uses the Java compiler which is currently set up in your shell. By default, the build uses Java 8. If you want to build with Java 11, you need to either add a build property -Duse.jdk11=true to your Ant build command or export the environment variable CASSANDRA_USE_JDK11=true. Otherwise, if you run the build using Java 11, the build script complains.

Now you can build Cassandra with the default task - just execute ant or ant jar. This may take a significant amount of time depending on artifacts that have to be downloaded or the number of classes that need to be compiled. When the build completes, you can find a JAR file in the build directory, and the database service can be started with the bin/cassandra script.

Some tasks you might be interested in are:

There are other tasks related to testing, and they are covered in Testing section.

IntelliJ IDEA by JetBrains is one of the most popular IDEs for Cassandra and Java development in general. The Community Edition can be freely downloaded with all features needed to get started developing Cassandra.

Use the following procedure for Cassandra 2.1.5+:

The project generated by ant generate-idea-files contains nearly everything you need to debug Cassandra and execute unit tests.

You should be able to:

Apache NetBeans is the elder of the open sourced java IDEs, and can be used for Cassandra development. There is no project setup or generation required to open Cassandra in NetBeans. Use the following procedure for Cassandra 4.0+.

First, clone and build Cassandra. Then execute the following steps to use NetBeans.

You should be able to:

These capabilities use the build.xml script. Build/Run/Debug Project are available via the Run/Debug menus, or the project context menu. Profile Project is available via the Profile menu. In the opened Profiler tab, click the green "Profile" button. Cassandra’s code style is honored in ide/nbproject/project.properties. The JAVA8_HOME system environment variable must be set for NetBeans to execute the Run/Debug/Profile ant targets to execute.

Eclipse is a popular open source IDE that can be used for Cassandra development. Various Eclipse environments are available from the download page. The following guide was created with "Eclipse IDE for Java Developers".

These instructions were tested on Ubuntu 16.04 with Eclipse Neon (4.6) using Cassandra versions 2.1 through 3.x.

First, clone and build Cassandra. Then execute the following steps to use Eclipse.

Find the project in Package Explorer or Project Explorer. You should not get errors if you build the project automatically using these instructions. Don’t set up the project before generating the files with ant.

You should be able to:

Unit tests can be run from Eclipse by simply right-clicking the class file or method and selecting Run As > JUnit Test. Tests can be debugged by defining breakpoints (double-click line number) and selecting Debug As > JUnit Test.

Alternatively all unit tests can be run from the command line as described in testing.

You may sometimes encounter some odd build failures when running the ant commands above. If you do, start ant with the realclean option:

Remember that all the tasks mentioned above may depend on building source files. If there are actual compilation errors in the code, you may not be able to generate project files for IntelliJ Idea, Netbeans, or Eclipse. It is especially important that you have imported the project adequately into IDE before doing merges or rebases. Otherwise, if there are conflicts, the project cannot be opened in IDE, and you will be unable to use any fancy conflict resolution tools offered by those IDEs.

To run the unit tests:

However, this is probably not what you want to do, since that command would run all the unit tests (those from test/unit). It would take about an hour or more to finish.

To run the specific test class or even a method, use the following command:

You can also use the IDE to run the tests - when you generate IDE files and properly import the Cassandra project, you can run the tests by right-clicking on the test class or package name. Remember that it is not enough to compile with IDE for some tests, and you need to call ant jar to build the distribution artifacts. When the test runs some tool as an external process, the tool expects Cassandra artifacts to be in the build directory.

Note that those commands apply to the tests in the test/unit directory. There are, however, some other test categories that have tests in individual directories:

Stress and FQLTool are separate modules located under the tools directory in the Cassandra project. They have their own source code and unit tests. To run the tests for those tools, first, build jar artifacts for them by calling:

Then you can execute the tests with either one of the commands:

or using your IDE.

JVM distributed tests can run a cluster of nodes inside a single JVM - they utilize a particular framework (that can be found at apache/cassandra-in-jvm-dtest-api) for that purpose. Those tests are intended to test features that require more started nodes or verify specific behaviors when the nodes get restarted, including upgrading them from one version to another. The tests are located at the test/distributed directory of the Cassandra project; however, only org.apache.cassandra.distributed.test and org.apache.cassandra.upgrade packages contain the actual tests. The rest of the files are various utilities related to the distributed test framework.

The distributed tests can be run in few ways. ant test-jvm-dtest command runs all the distributed JVM tests. It is not very useful; thus, there is also ant test-jvm-dtest-some, which allows specifying test class and test name in the similar way as you could do that for the ant testsome command, for example:

Distributed tests can also be run using IDE (in fact, you can even debug them).

It is possible to define a list of test classes to run with a single command. Define a text file, by default called testlist.txt, and put it into your project directory. Here is an example of that file:

Essentially, you list the paths to the class files of the tests you want to run. Then you call ant testclasslist, which uses the text file to run the listed tests. Note that, by default, it applies to the tests under the test/unit directory and takes the testlist.txt file, but this behavior can be modified by providing additional parameters:

For example, if you want to run the distributed tests this way, and say our tests were listed in the distributed-tests-set.txt file (paths to test classes relative to test/distributed directory), you can do that by calling:

Coverage reports from the executed JVM tests can be obtained in two ways - through IDE - for example, IntelliJ supports running tests with coverage analysis (another run button next to the one for running in debug mode).

The other way is to run Ant target codecoverage. Basically, it works for all the ways mentioned above of running JVM tests - the only difference is that instead of specifying the target directly, you pass it as a property called taskname. For example - given the original test command is:

to run it with coverage analysis, do:

It applies to all the targets like test, testsome, test-long, etc., even testclasslist. You can find the coverage report in build/jacoco (index.html is the entry point for the HTML version, but there are also XML and CSV reports).

Note that if you run various tests that way, the coverage information is added to the previously collected runs. That is, you get the cumulative coverage from all runs unless you clean up the project or at least clean up the recorded coverage information by executing the command ant jacoco-cleanup.

To run micro-benchmarks, first build the uber jar for the JMH framework. Use the following ant command:

Then, you can run either all benchmarks (from the test/microbench directory) or the tests matching the name specified by the benchmark.name property when executing the ant microbench command. Whether you run all benchmarks or just a selected one, only classes under the microbench package are selected. The class selection pattern is actually .*microbench.*${benchmark.name}. For example, in order to run org.apache.cassandra.test.microbench.ChecksumBench, execute:

The ant microbench command runs the benchmarks with default parameters as defined in the build.xml file (see the microbench target definition). If you want to run JMH with custom parameters, consider using the test/bin/jmh script. In addition to allowing you to customize JMH options, it also sets up the environment and JVM options by running Cassandra init script (conf/cassandra-env.sh). Therefore, it lets the environment for running the tests to be more similar to the production environment. For example:

You may also find it useful to run the command to list all the tests: test/bin/jmh -l or test/bin/jmh -lp (also showing the default parameters). The list of all options can be shown by running test/bin/jmh -h

The Docker approach is recommended for running Python distributed tests. The behavior will be more repeatable, matching the same environment as the official testing on Cassandra CI.

CQLSH tests are located in the pylib/cqlshlib/test directory. There is a helper script that runs the tests for you. In particular, it builds the Cassandra project, creates a virtual environment, runs the CCM cluster, executes the tests, and eventually removes the cluster. You find the script in the pylib directory. The only argument it requires is the Cassandra project directory:

Refer to the README for further information.

One way of doing integration or system testing at larger scale is using dtest (Cassandra distributed test). These dtests automatically setup Cassandra clusters with certain configurations and simulate use cases you want to test.

The best way to learn how to write dtests is probably by reading the introduction "http://www.datastax.com/dev/blog/how-to-write-a-dtest[How to Write a Dtest]". Looking at existing, recently updated tests in the project is another good activity. New tests must follow certain style conventions that are checked before contributions are accepted. In contrast to Cassandra, dtest issues and pull requests are managed on github, therefore you should make sure to link any created dtests in your Cassandra ticket and also refer to the ticket number in your dtest PR.

Creating a good dtest can be tough, but it should not prevent you from submitting patches! Please ask in the corresponding JIRA ticket how to write a good dtest for the patch. In most cases a reviewer or committer will able to support you, and in some cases they may offer to write a dtest for you.

Avoid extraneous words, for example prefer x() over getX() or setX() where it makes semantic sense. At the same time, do not avoid using words that are necessary, for example if a descriptive word provides semantic context such as liveReplicas over replicas. This is essential when there are many conceptual instantiations for a variable that are not enforced by the type system, but be sure to be consistent in the word choice and order across all instantiations of the variable.

e.g. allReplicas, naturalReplicas, pendingReplicas, allLiveReplicas, etc.

Ensure consistency of naming within a method, and between methods. It may be that multiple names are appropriate for a concept, but these should not be mixed and matched within the project. If you modify a concept, or improve the naming of a concept, make all relevant - including existing - code consistent with the new terminology. If possible, correspond with a prior author before modifying their semantics.

If possible, enforce semantic distinctions at compile time with the type system.

e.g. RangesAtEndpoint, EndpointsForRange and EndpointsForToken are all semantically different variants on a collection of replicas.

This makes the intent of the code clearer, and helps the compiler indicate where we may have unintentionally conflated concepts. They also provide opportunities to insert stronger runtime checks that our assumptions hold, and these constraints can provide further clarity when reading the code.

In the case of EndpointsForX, for instance, we enforce that we have no duplicate endpoints, and that all of the endpoints do fully cover X.

If a separate type for all concepts is too burdensome, a type that aggregates concepts together within member variables might be applicable.

The most obvious counter-example is not to use Pair, or a similar tuple. Unless it is extremely obvious, prefer a dedicated type with well named member variables.

For example, FetchReplicas for source and target replicas, and ReplicaLayout for the distinction between natural and pending replicas.

This may help authors notice other semantics they had overlooked, that might have led to subtly incorrect parameter provision to methods. Conversely, methods may choose to accept one of these encapsulating types, so that callers do not need to consider which member they should provide.

e.g. ConsistencyLevel.assureSufficientLiveReplicas requires very specific replica collections, that are quite distinct, that might be easily incorrectly provided (though this is still inadequate, as it needs to distinguish between live and non-live semantics, which remains to be improved)

These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.

If an interface has only one implementation, remove it. If a method isn’t used, delete it.

Don’t implement hashCode(), equals(), toString() or other methods unless they provide immediate utility.

Don’t overgeneralise. Implement the most specific method or class that you can, that handles the present use cases.

Methods and classes should have a single clear purpose, and should avoid special-cases where practical.

Consider where your methods and inner classes live with respect to each other. Methods that are of a similar category should be adjacent, as should methods that are primarily dependent on each other. Try to use a consistent pattern, e.g. helper methods may occur either before or after the method that uses them, but not both; method signatures that cover different combinations of parameters should occur in a consistent order visiting the parameter space.

Class declaration order should, approximately, go: inner classes, static properties, instance properties, constructors (incl static factory methods), getters/setters, main functional/API methods, helper (incl static) methods and classes. Clarity should always come first, however.

A method should be short. There is no hard size limit, but a filled screen is a good warning size. However, be careful not to over-minimise your methods; a page of tiny functions is also hard to read.

The body of a method should be limited to the main conceptual work being done. Substantive ancillary logic, such as computing an intermediate result, evaluating complex predicates, performing auditing, logging, etc, are prime candidates for helper methods.

Always use @Override annotations when implementing abstract or interface methods or overriding a parent method.

@Nullable, @NonNull, @ThreadSafe, @NotThreadSafe and @Immutable should be used as appropriate to communicate to both the compiler and readers.

Prefer public final fields to private fields with getters (but prefer encapsulating behavior in "real" methods to either).

Declare class properties final wherever possible, but never declare local variables and parameters final. Variables and parameters should still be treated as immutable wherever possible, with explicit code blocks introduced as necessary to minimize the scope of any mutable variables.

Prefer initialization in a constructor to setters, and builders where the constructor is complex with many optional parameters.

Avoid redundant this references to member fields or methods, except for consistency with other assignments e.g. in the constructor

Never ever write catch (…) {} or catch (…) { logger.error() } merely to satisfy Java’s compile-time exception checking.

Always catch the narrowest exception type possible for achieving your goal. If Throwable must be caught for handling exceptional termination, it must be rethrown. If an exception cannot be safely handled locally, propagate it - but use unchecked exceptions if no caller expects to handle the case. Rethrow as RuntimeException, IOError, or your own UncheckedXException, or IllegalStateException if it “can’t happen”

Only if an exception is an explicitly acceptable condition can it be ignored, but this must be explained carefully in a comment detailing how this is handled correctly.

Where possible prefer keeping a logical action to a single line. Prefer introducing additional variables, or well-named methods encapsulating actions, to multi-line statements - unless this harms clarity (e.g. in an already short method).

Try to keep lines under 120 characters, but use good judgment. It is better to exceed this limit, than to split a line that has no natural splitting points, particularly when the remainder of the line is boilerplate or easily inferred by the reader.

If a line wraps inside a method call, first extract any long parameter expressions to local variables before trying to group natural parameters together on a single line, aligning the start of parameters on each line, e.g.

When splitting a ternary, use one line per clause, carry the operator, and where possible align the start of the ternary condition, e.g.

It is usually preferable to carry the operator for multiline expressions, with the exception of some multiline string literals.

Make sure to use 4 spaces instead of the tab character for all your indentation. Many lines in the current files have a bunch of trailing whitespace. If you encounter incorrect whitespace, clean up in a separate patch. Current and future reviewers won’t want to review whitespace diffs.

Consider using static imports for frequently used utility methods that are unambiguous. E.g. String.format, ByteBufferUtil.bytes, Iterables.filter/any/transform.

When naming static methods, select names that maintain semantic legibility when statically imported, and are unlikely to clash with other method names that may be mixed in the same context.

Observe the following order for your imports:

While logging, it is important to avoid forcing unnecessary work on a hot path. There might be an invocation of a log statement which might not reach a log endpoint hence it is evaluated unnecessarily. The if test beforehand should only be done if the log invocation is expected to do unnecessary work, e.g. construct a varargs array or do some costly string translation as part of the parameter construction to the log statement.

Other cases should be logged without wrapping it in if.

Submitted patches can include bug fixes, changes to the Java code base, improvements for tooling (both Java or Python), documentation, testing or any other changes that requires changing the code base. Although the process of contributing code is always the same, the amount of work and time it takes to get a patch accepted also depends on the kind of issue you’re addressing.

To create a JIRA account, please request it on the #cassandra or #cassandra-dev channels on ASF Slack, or on the user or dev mailing list.

Although contributions are highly appreciated, we do not guarantee that every contribution will become a part of Cassandra. Therefore, it’s generally a good idea to first get some feedback on the thing you plan to do, especially about any new features or major changes to the code base. You can reach out to other developers on the mailing list or Slack.

So you’ve finished coding and the great moment arrives: it’s time to submit your patch!

If you don’t know who is reviewing your change yet, you can use TBD and amend the commit later to note the people who helped you.

Alternatively, many contributors prefer to make their branch available on GitHub. In this case, fork the Cassandra repository on GitHub and push your branch:

Once the review process is complete, you will receive a +1. Wait for a committer to commit it. Do not delete your branches immediately after they’ve been committed - keep them on GitHub for a while. Alternatively, attach a patch to JIRA for historical record. It’s not that uncommon for a committer to mess up a merge. In case of that happening, access to the original code is required, or else you’ll have to redo some of the work.

Cassandra can be automatically tested using various test suites, that are either implemented based on JUnit or the dtest scripts written in Python. As outlined in testing, each kind of test suite addresses a different way to test Cassandra. Eventually, all of the tests will be executed together on the CI platform at builds.apache.org, running Jenkins.

Jenkins is an open source solution that can be installed on a large number of platforms. Setting up a custom Jenkins instance for Cassandra may be desirable for users who have hardware to spare, or organizations that want to run Cassandra tests for custom patches before contribution.

Please refer to the Jenkins download and documentation pages for details on how to get Jenkins running, possibly also including slave build executor instances. The rest of the document will focus on how to setup Cassandra jobs in your Jenkins environment.

Cassandra ships with a default CircleCI configuration to enable running tests on your branches. Go to the CircleCI website, click "Login" and log in with your github account. Then give CircleCI permission to watch your repositories.

Once you have done that, you can optionally configure CircleCI to run tests in parallel if you wish:

To update dependencies, update the parent and child POM definitions in build.xml. The parent POM should include the dependency tag with groupId, artifactId, version, and optional scope fields. The child POM(s) should include the dependency tag with groupId and artifactId. See the Maven docs for a complete reference on how to reference dependencies across parent and child POMs.

Here is an example of a commit that changes dependency versions pre-5.0.

In Cassandra 5.0 and later, dependencies are managed in Maven POM templates in .build/*-template.xml. These templates are processed into valid Maven POMs and copied to build/\*.pom by the ant write-poms task.

For new dependencies, add to parent-pom-template and cassandra-deps-template, and optionally cassandra-build-deps-template if the dependency is required for build only. See the Maven docs on how to reference dependencies in the parent POM from the child POMs.

For dependency versions that need to be available in build.xml and parent-pom-template, specify the version as a property in build.xml, add it to the ant write-poms target, then add the property to parent-pom-template with the value of the template substitution.

Here is an example of a commit that changes dependency versions since 5.0.

Here are some useful commands that may help you out resolving conflicts.

The official Cassandra documentation lives in the project’s git repository. We use a static site generator, Antora, to create pages hosted at cassandra.apache.org.

<!-- You’ll also find developer-centric content about Cassandra internals in our retired wiki (not covered by this guide). -→

Using a static site generator often requires the use of a markup language instead of visual editors (which some people would call good news). Antora processes AsciiDoc, the markup language used to generate our documentation. Markup languages allow you to format text using certain syntax elements. Your document structure will also have to follow specific conventions. Feel free to take a look at existing documents to get a better idea how we structure our documents.

So how do you actually start making contributions?

Recommended for shorter documents and minor changes on existing content (e.g. fixing typos or updating descriptions)

Follow these steps to contribute using GitHub. It’s assumed that you’re logged in with an existing account.

Make sure to preview added content before committing any changes.

Afterwards the GitHub Cassandra mirror will list your pull request and you’re done. Congratulations! Please give us some time to look at your suggested changes before we get back to you.

Recommended for major changes

Significant changes to the documentation are best managed through our Jira issue tracker. Please follow the same contribution guides as for regular code contributions. Creating high quality content takes a lot of effort. It’s therefore always a good idea to create a ticket before you start and explain what you’re planning to do. This will create the opportunity for other contributors and committers to comment on your ideas and work so far. Eventually your patch gets a formal review before it is committed.

Recommended for advanced editing

Using the GitHub web interface should allow you to use most common layout elements including images. More advanced formatting options and navigation elements depend on Antora to render correctly. Therefore, it’s a good idea to setup Antora locally for any serious editing. Please follow the instructions in the Cassandra source directory at doc/README.md. Setup is very easy (at least on OSX and Linux).

Please feel free to get involved and merge pull requests created on the GitHub mirror if you’re a committer. As this is a read-only repository, you won’t be able to merge a PR directly on GitHub. You’ll have to commit the changes against the Apache repository with a comment that will close the PR when the committ syncs with GitHub.

You may use a git work flow like this:

Now either rebase or squash the commit, e.g. for squashing:

Make sure to add a proper commit message including a "Closes #<PR-ID>" text to automatically close the PR.

A debian based linux OS is required to run the release steps from. Debian-based distros provide the required RPM, dpkg and repository management tools.

Any committer can perform the following steps to create and call a vote on a proposed release.

Check that there are no open urgent Jira tickets currently being worked on. Also check with the PMC that there’s security vulnerabilities currently being worked on in private. Current project habit is to check the timing for a new release on the dev mailing lists.

For successful building process, install this tooling locally: svn, git, ant, devscripts, reprepro, rpmsign, docker, createrepo (the script is checking this tooling is present before proceeding any further). The names of these "packages" are Debian-centric, but equivalents should be discoverable in other systems too.

There is a package called createrepo-c in Debian Bullseye. Please beware that createrepo package is not located in Ubuntu 20.04 LTS. createrepo package is present in Ubuntu Bionic (18.04), createrepo-c is in Ubuntu Jammy (22.04 LTS) and more recent.

Fill out the following email template you find in $HOME/Mail directory and send to the dev mailing list:

Any PMC member can perform the following steps to formalize and publish a successfully voted release.

See docs for building and publishing the website.

Also update the CQL doc if appropriate.

Release the JIRA version.

Update the codebase to point to the next development version:

Wait for the artifacts to sync at downloads.apache.org/cassandra/

Fill out the following email template and send to both user and dev mailing lists:

Update Slack Cassandra topic ---------------------------

Tweet the new release, from the @Cassandra account

As described in When to Archive.

An example of removing old releases: