---
layout: docpage

title: "Documentation"

is_homepage: false
is_sphinx_doc: true

doc-parent: "Contributing to Cassandra"

doc-title: "Contributing Code Changes"
doc-header-links: '
  <link rel="top" title="Apache Cassandra Documentation v4.0-beta4" href="../index.html"/>
      <link rel="up" title="Contributing to Cassandra" href="index.html"/>
      <link rel="next" title="Code Style" href="code_style.html"/>
      <link rel="prev" title="Testing" href="testing.html"/>
'
doc-search-path: "../search.html"

extra-footer: '
<script type="text/javascript">
    var DOCUMENTATION_OPTIONS = {
      URL_ROOT:    "",
      VERSION:     "",
      COLLAPSE_INDEX: false,
      FILE_SUFFIX: ".html",
      HAS_SOURCE:  false,
      SOURCELINK_SUFFIX: ".txt"
    };
</script>
'

---
<div class="container-fluid">
  <div class="row">
    <div class="col-md-3">
      <div class="doc-navigation">
        <div class="doc-menu" role="navigation">
          <div class="navbar-header">
            <button type="button" class="pull-left navbar-toggle" data-toggle="collapse" data-target=".sidebar-navbar-collapse">
              <span class="sr-only">Toggle navigation</span>
              <span class="icon-bar"></span>
              <span class="icon-bar"></span>
              <span class="icon-bar"></span>
            </button>
          </div>
          <div class="navbar-collapse collapse sidebar-navbar-collapse">
            <form id="doc-search-form" class="navbar-form" action="../search.html" method="get" role="search">
              <div class="form-group">
                <input type="text" size="30" class="form-control input-sm" name="q" placeholder="Search docs">
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </div>
            </form>
            
            
            <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../getting_started/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../new/index.html">New Features in Apache Cassandra 4.0</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/index.html">Architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cql/index.html">The Cassandra Query Language (CQL)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data_modeling/index.html">Data Modeling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../configuration/index.html">Configuring Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../operating/index.html">Operating Cassandra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Cassandra Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../troubleshooting/index.html">Troubleshooting</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Contributing to Cassandra</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="ide.html">Building and IDE Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Contributing Code Changes</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#choosing-what-to-work-on">Choosing What to Work on</a></li>
<li class="toctree-l3"><a class="reference internal" href="#before-you-start-coding">Before You Start Coding</a></li>
<li class="toctree-l3"><a class="reference internal" href="#creating-a-patch">Creating a Patch</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="code_style.html">Code Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="how_to_review.html">Review Checklist</a></li>
<li class="toctree-l2"><a class="reference internal" href="how_to_commit.html">How-to Commit</a></li>
<li class="toctree-l2"><a class="reference internal" href="documentation.html">Working on Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">Jenkins CI Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="dependencies.html">Dependency Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="release_process.html">Release Process</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../plugins/index.html">Third-Party Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contactus.html">Contact us</a></li>
</ul>

            
          </div><!--/.nav-collapse -->
        </div>
      </div>
    </div>
    <div class="col-md-8">
      <div class="content doc-content">
        <div class="content-container">
          
  <div class="section" id="contributing-code-changes">
<span id="patches"></span><h1>Contributing Code Changes<a class="headerlink" href="#contributing-code-changes" title="Permalink to this headline">¶</a></h1>
<div class="section" id="choosing-what-to-work-on">
<h2>Choosing What to Work on<a class="headerlink" href="#choosing-what-to-work-on" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<dl class="docutils">
<dt>As a general rule of thumb:</dt>
<dd><ul class="first last simple">
<li>Major new features and significant changes to the code based will likely not going to be accepted without deeper discussion within the <a class="reference external" href="http://cassandra.apache.org/community/">developer community</a></li>
<li>Bug fixes take higher priority compared to features</li>
<li>The extend to which tests are required depend on how likely your changes will effect the stability of Cassandra in production. Tooling changes requires fewer tests than storage engine changes.</li>
<li>Less complex patches will be faster to review: consider breaking up an issue into individual tasks and contributions that can be reviewed separately</li>
</ul>
</dd>
</dl>
<div class="admonition hint">
<p class="first admonition-title">Hint</p>
<p class="last">Not sure what to work? Just pick an issue marked as <a class="reference external" href="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</a> Complexity in JIRA, which we use to flag issues that could turn out to be good starter tasks for beginners.</p>
</div>
</div>
<div class="section" id="before-you-start-coding">
<h2>Before You Start Coding<a class="headerlink" href="#before-you-start-coding" title="Permalink to this headline">¶</a></h2>
<p>Although contributions are highly appreciated, we do not guarantee that each contribution will become a part of Cassandra. Therefore it’s generally a good idea to first get some feedback on the things you plan to work on, especially about any new features or major changes to the code base. You can reach out to other developers on the mailing list or <a class="reference internal" href="../contactus.html#slack"><span class="std std-ref">Slack</span></a>.</p>
<dl class="docutils">
<dt>You should also</dt>
<dd><ul class="first last simple">
<li>Avoid redundant work by searching for already reported issues in <a class="reference external" href="https://issues.apache.org/jira/browse/CASSANDRA">JIRA</a></li>
<li>Create a new issue early in the process describing what you’re working on - not just after finishing your patch</li>
<li>Link related JIRA issues with your own ticket to provide a better context</li>
<li>Update your ticket from time to time by giving feedback on your progress and link a GitHub WIP branch with your current code</li>
<li>Ping people who you actively like to ask for advice on JIRA by <a class="reference external" href="https://confluence.atlassian.com/conf54/confluence-user-s-guide/sharing-content/using-mentions">mentioning users</a></li>
</ul>
</dd>
<dt>There are also some fixed rules that you need to be aware:</dt>
<dd><ul class="first last simple">
<li>Patches will only be applied to branches by following the release model</li>
<li>Code must be testable</li>
<li>Code must follow the <a class="reference internal" href="code_style.html"><span class="doc">Code Style</span></a> convention</li>
<li>Changes must not break compatibility between different Cassandra versions</li>
<li>Contributions must be covered by the Apache License</li>
</ul>
</dd>
</dl>
<div class="section" id="choosing-the-right-branches-to-work-on">
<h3>Choosing the Right Branches to Work on<a class="headerlink" href="#choosing-the-right-branches-to-work-on" title="Permalink to this headline">¶</a></h3>
<p>There are currently multiple Cassandra versions maintained in individual branches:</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Version</th>
<th class="head">Policy</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>4.0</td>
<td>Code freeze (see below)</td>
</tr>
<tr class="row-odd"><td>3.11</td>
<td>Critical bug fixes only</td>
</tr>
<tr class="row-even"><td>3.0</td>
<td>Critical bug fixes only</td>
</tr>
<tr class="row-odd"><td>2.2</td>
<td>Critical bug fixes only</td>
</tr>
<tr class="row-even"><td>2.1</td>
<td>Critical bug fixes only</td>
</tr>
</tbody>
</table>
<p>Corresponding branches in git are easy to recognize as they are named <code class="docutils literal notranslate"><span class="pre">cassandra-&lt;release&gt;</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">cassandra-3.0</span></code>). The <code class="docutils literal notranslate"><span class="pre">trunk</span></code> 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.</p>
<div class="section" id="code-freeze">
<h4>4.0 Code Freeze<a class="headerlink" href="#code-freeze" title="Permalink to this headline">¶</a></h4>
<p>Patches for new features are currently not accepted for 4.0 or any earlier versions. Starting with the code freeze in September, 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:</p>
<blockquote>
<div><ul class="simple">
<li>Bug fixes</li>
<li>Measurable performance improvements</li>
<li>Changes not distributed as part of the release such as:</li>
<li>Testing related improvements and fixes</li>
<li>Build and infrastructure related changes</li>
<li>Documentation</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="bug-fixes">
<h4>Bug Fixes<a class="headerlink" href="#bug-fixes" title="Permalink to this headline">¶</a></h4>
<p>Creating patches for bug fixes is a bit more complicated as this will depend on how many different versions of Cassandra are affected. In each case, the order for merging such changes will be <code class="docutils literal notranslate"><span class="pre">cassandra-2.1</span></code> -&gt; <code class="docutils literal notranslate"><span class="pre">cassandra-2.2</span></code> -&gt; <code class="docutils literal notranslate"><span class="pre">cassandra-3.0</span></code> -&gt; <code class="docutils literal notranslate"><span class="pre">cassandra-3.x</span></code> -&gt; <code class="docutils literal notranslate"><span class="pre">trunk</span></code>. But don’t worry, merging from 2.1 would be the worst case for bugs that affect all currently supported versions, which isn’t very common. As a contributor, you’re also not expected to provide a single patch for each version. What you need to do however is:</p>
<blockquote>
<div><ul class="simple">
<li>Be clear about which versions you could verify to be affected by the bug</li>
<li>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</li>
<li>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)</li>
<li>Test if the patch can be merged cleanly across branches in the direction listed above</li>
<li>Be clear which branches may need attention by the committer or even create custom patches for those if you can</li>
</ul>
</div></blockquote>
</div>
</div>
</div>
<div class="section" id="creating-a-patch">
<h2>Creating a Patch<a class="headerlink" href="#creating-a-patch" title="Permalink to this headline">¶</a></h2>
<p>So you’ve finished coding and the great moment arrives: it’s time to submit your patch!</p>
<blockquote>
<div><ol class="arabic simple">
<li>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. <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">-b</span> <span class="pre">12345-3.0</span></code></li>
<li>Verify that you follow Cassandra’s <a class="reference internal" href="code_style.html"><span class="doc">Code Style</span></a></li>
<li>Make sure all tests (including yours) pass using ant as described in <a class="reference internal" href="testing.html"><span class="doc">Testing</span></a>. 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 <a class="reference external" href="https://builds.apache.org/">CI</a> 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.</li>
<li>Consider going through the <a class="reference internal" href="how_to_review.html"><span class="doc">Review Checklist</span></a> for your code. This will help you to understand how others will consider your change for inclusion.</li>
<li>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:</li>
</ol>
<blockquote>
<div><ol class="loweralpha simple">
<li>Attach a patch to JIRA with a single squashed commit in it (per branch), or</li>
<li>Squash the commits in-place in your branches into one</li>
</ol>
</div></blockquote>
<ol class="arabic" start="6">
<li><p class="first">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 <a class="reference external" href="https://lists.apache.org/thread.html/rde1128131a621e43b0a9c88778398c053a234da0f4c654b82dcbbe0e%40%3Cdev.cassandra.apache.org%3E">should</a> 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.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&lt;One sentence description, usually Jira title and CHANGES.txt summary&gt;
&lt;Optional lengthier description&gt;
patch by &lt;Authors&gt;; reviewed by &lt;Reviewers&gt; for CASSANDRA-#####
</pre></div>
</div>
</li>
<li><p class="first">When you’re happy with the result, create a patch:</p>
</li>
</ol>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git add &lt;any new or modified file&gt;
git commit -m &#39;&lt;message&gt;&#39;
git format-patch HEAD~1
mv &lt;patch-file&gt; &lt;ticket-branchname.txt&gt; (e.g. 12345-trunk.txt, 12345-3.0.txt)
</pre></div>
</div>
<p>Alternatively, many contributors prefer to make their branch available on GitHub. In this case, fork the Cassandra repository on GitHub and push your branch:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>git push --set-upstream origin 12345-3.0
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple" start="8">
<li>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.</li>
<li>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.</li>
<li>Wait for other developers or committers to review it and hopefully +1 the ticket (see <a class="reference internal" href="how_to_review.html"><span class="doc">Review Checklist</span></a>). 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.</li>
<li>If the reviewer has given feedback to improve the patch, make the necessary changes and move the ticket into “Patch Available” once again.</li>
</ol>
</div></blockquote>
<p>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.</p>
</div>
</div>


          <div class="doc-prev-next-links" role="navigation" aria-label="footer navigation">
            
            <a href="code_style.html" class="btn btn-default pull-right " role="button" title="Code Style" accesskey="n">Next <span class="glyphicon glyphicon-circle-arrow-right" aria-hidden="true"></span></a>
            
            
            <a href="testing.html" class="btn btn-default" role="button" title="Testing" accesskey="p"><span class="glyphicon glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a>
            
          </div>
          
        </div>
      </div>
    </div>
  </div>
</div>