site-content/source/modules/ROOT/pages/development/patches.adoc

:page-layout: basic

== Contributing Code Changes

=== Choosing What to Work on

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.

As a general rule of thumb:::
  * Major new features and significant changes to the code base will
  likely not be accepted without deeper discussion within the
  http://cassandra.apache.org/community/[developer community].
  * Bug fixes take higher priority compared to features.
  * The extent to which tests are required depends on how likely your
  changes will effect the stability of Cassandra in production. Tooling
  changes requires fewer tests than storage engine changes.
  * Less complex patches will be reviewed faster; consider breaking up
  an issue into individual tasks and contributions that can be reviewed
  separately.

[TIP]
.Hint
====
Not sure what to work? Just pick an issue marked as
https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSANDRA%20AND%20Complexity%20%3D%20%22Low%20Hanging%20Fruit%22%20and%20status%20!%3D%20resolved[Low
Hanging Fruit] Complexity in JIRA, which flags issues that often turn out to be good starter tasks for beginners.
====

To create a JIRA account, please request it on xref:community.adoc#discussions[the #cassandra or #cassandra-dev channels on ASF Slack], or on xref:community.adoc#discussions[the user or dev mailing list].

=== Before You Start Coding

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`.

You should also::
  * Avoid redundant work by searching for already reported issues in
  https://issues.apache.org/jira/browse/CASSANDRA[JIRA] to work on.
  * Create a new issue early in the process describing what you're
  working on - before finishing your patch.
  * Link related JIRA issues with your own ticket to provide a better
  context.
  * Update your ticket from time to time by giving feedback on your
  progress and link a GitHub WIP branch with your current code.
  * Ping people who you actively like to ask for advice on JIRA by
  https://confluence.atlassian.com/doc/mentions-251725350.html[mentioning users].

There are also some fixed rules that you need to be aware::
  * Patches will only be applied to branches by following the release
  model
  * Code must be testable
  * Code must follow the xref:development/code_style.adoc[code style] convention
  * Changes must not break compatibility between different Cassandra
  versions
  * Contributions must be covered by the Apache License

==== Choosing the Right Branches to Work on

There are currently multiple Cassandra versions maintained in individual
branches:

[cols=",",options="header",]
|===
|Version |Policy
|4.0     |Code freeze (see below)
|3.11    |Critical bug fixes only
|3.0     |Critical bug fixes only
|2.2     |Critical bug fixes only
|2.1     |Critical bug fixes only
|===

Corresponding branches in git are easy to recognize as they are named
`cassandra-<release>` (e.g. `cassandra-3.0`). The `trunk` branch is an
exception, as it contains the most recent commits from all other
branches and is used for creating new branches for future tick-tock
releases.

==== 4.0 Code Freeze

Patches for new features are currently not accepted for 4.0 or any
earlier versions.
All efforts should focus on stabilizing the 4.0 branch before the first
official release. During that time, only the following patches will be
considered for acceptance:

* Bug fixes
* Measurable performance improvements
* Changes not distributed as part of the release such as:
* Testing related improvements and fixes
* Build and infrastructure related changes
* Documentation

==== Bug Fixes

Creating patches for bug fixes is a bit more complicated and will
depend on how many different versions of Cassandra are affected. In each
case, the order for merging such changes will be `cassandra-2.1` ->
`cassandra-2.2` -> `cassandra-3.0` -> `cassandra-3.x` -> `trunk`.
But don't worry, merging from 2.1 would be the worst case for bugs that
affect all currently supported versions, an uncommon event. As a
contributor, you're also not expected to provide a single patch for each
version. What you need to do however is:

* Be clear about which versions you could verify to be affected by the
bug
* For 2.x: ask if a bug qualifies to be fixed in this release line, as
this may be handled on case by case bases
* If possible, create a patch against the lowest version in the branches
listed above (e.g. if you found the bug in 3.9 you should try to fix it
already in 3.0)
* Test if the patch can be merged cleanly across branches in the
direction listed above
* Be clear which branches may need attention by the committer or even
create custom patches for those if you can

=== Creating a Patch

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

[arabic]
. Create a branch for your changes if you haven't done already. Many
contributors name their branches based on ticket number and Cassandra
version, e.g. `git checkout -b 12345-3.0` or
`git checkout -b CASSANDRA-12345-3.0`.

[TIP]
.Hint
====
When working on multiple patches at the same time, instead of cloning
the repository separately for each of them, set up multiple
working trees for different Cassandra versions from the same repository
using https://git-scm.com/docs/git-worktree[Git worktrees] feature.
====

. Verify that you follow Cassandra's xref:development/code_style.adoc[code style]
. Make sure all tests (including yours) pass using ant as described in
xref:development/testing.adoc[testing]. If you suspect a test failure
is unrelated to your change, it may be useful to check the test's
status by searching the issue tracker or looking at
https://builds.apache.org/[CI] results for the relevant upstream
version. Note that the full test suites take many hours to complete,
so it is common to only run specific relevant tests locally before
uploading a patch. Once a patch has been uploaded, the reviewer or
committer can help setup CI jobs to run the full test suites.
. Consider going through the xref:development/how_to_review.adoc[how
to review] page for your code. This will help you to understand how
others will consider your change for inclusion.
. Don’t make the committer squash commits for you in the root branch
either. Multiple commits are fine - and often preferable - during review
stage, especially for incremental review, but once +1d, do either:

[loweralpha]
. Attach a patch to JIRA with a single squashed commit in it (per
branch), or
. Squash the commits in-place in your branches into one

[arabic, start=6]
. Include a CHANGES.txt entry (put it at the top of the list), and
format the commit message appropriately in your patch as below. Please
note that only user-impacting items
https://lists.apache.org/thread.html/rde1128131a621e43b0a9c88778398c053a234da0f4c654b82dcbbe0e%40%3Cdev.cassandra.apache.org%3E[should]
be listed in CHANGES.txt. If you fix a test that does not affect users
and does not require changes in runtime code, then no CHANGES.txt entry
is necessary.
+
[source,none]
----
<One sentence description, usually Jira title and CHANGES.txt summary>
<Optional lengthier description>
patch by <Authors>; reviewed by <Reviewers> for CASSANDRA-#####
----
[arabic, start=7]
. When you're happy with the result, create a patch. We suggest that
you use a similar format (note blank lines) for the commit log message:

+
[source,none]
----
<one sentence description>

<optional lengthier description>

Patch by <authors>; reviewed by <Reviewers> for CASSANDRA-#####
----

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.

[source,none]
----
git add <any new or modified file>
git commit
git format-patch HEAD~1
mv <patch-file> <ticket-branchname.txt> (e.g. 12345-trunk.txt, 12345-3.0.txt)
----

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

[source,none]
----
git push --set-upstream origin 12345-3.0
----

[arabic, start=8]
. To make life easier for your reviewer/committer, you may want to make
sure your patch applies cleanly to later branches and create additional
patches/branches for later Cassandra versions to which your original
patch does not apply cleanly. That said, this is not critical, and you
will receive feedback on your patch regardless.
. Attach the newly generated patch to the ticket/add a link to your
branch and click "Submit Patch" at the top of the ticket. This will move
the ticket into "Patch Available" status, indicating that your
submission is ready for review.
. Wait for other developers or committers to review it and hopefully
+1 the ticket (see xref:development/how_to_review.adoc[how to
review]). If your change does not receive a +1, do not be discouraged.
If possible, the reviewer will give suggestions to improve your patch
or explain why it is not suitable.
. If the reviewer has given feedback to improve the patch, make the
necessary changes and move the ticket into "Patch Available" once again.
. Once you've had the patch reviewed you can amend the commit to update
the commit message `TBD` with the reviewers who helped you.

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.