Overview

  1. Pick an issue to work on. If you don't have a specific itch to scratch, some possibilities are marked with the low-hanging fruit label in JIRA.

  2. Read the relevant parts of ArchitectureInternals; watching http://www.youtube.com/watch?v=W6e8_IcgJM4 will probably also be useful

  3. Check if someone else has already begun work on the change you have in mind in the issue tracker

  4. If not, create a ticket describing the change you're proposing in the issue tracker
  5. Check out the latest version of the source code
  6. Modify the source to include the improvement/bugfix
    • Verify that you follow Cassandra's CodeStyle.

    • Verify that your change works by adding a unit test.
    • Make sure all tests pass by running "ant test" in the project directory.
      • You can run specific tests like so: ant test -Dtest.name=SSTableReaderTest`

    • For testing multi-node behavior, https://github.com/pcmanus/ccm is useful

  7. When you're happy with the result create a patch:
    • git add <any new or modified file>

    • git diff --cached > branchname-issue.txt (e.g. trunk-123.txt, cassandra-0.6-123.txt)

  8. Attach the newly generated patch to the issue and click "Submit patch" in the left side of the JIRA page
  9. Wait for other developers or committers to review it and hopefully +1 the ticket
  10. Wait for a committer to commit it.

Testing and Coverage

Setting up and running system tests:

Running the functional tests for Thrift RPC

  1. Install CQL: svn checkout https://svn.apache.org/repos/asf/cassandra/drivers; cd drivers/py; python setup.py build; sudo python setup.py install.

  2. Install the nose test runner (aptitude install python-nose, easy_install nose, etc).

  3. Install the Thrift compiler (see InstallThrift) and Python libraries (cd thrift/lib/py && python setup.py install).

  4. Generate Cassandra's Python code using ant gen-thrift-py.

  5. Build the source ant clean build.

  6. Run nosetests test/system/ from the top-level source directory.

If you need to modify the system tests, you probably only need to care about test/system/test_thrift_server.py. (test/system/init.py takes care of spawning new cassandra instances for each test and cleaning up afterwards so they are isolated.)

Running the code coverage task

  1. Unzip this one: http://sourceforge.net/projects/cobertura/files/cobertura/1.9.4.1/cobertura-1.9.4.1-bin.zip/download

  2. ant codecoverage -Dcobertura.dir=/path/to/cobertura

  3. /path/to/cobertura/cobertura-report.sh --destination build/cobertura/html source code src/java

  4. View build/cobertura/html/index.html

Continuous integration

Buildbot runs the Cassandra tests continuously: http://ci.apache.org/builders/cassandra-trunk. (Builders for stable branches also exist.)

IDE

Ivy

Cassandra uses ivy [http://ant.apache.org/ivy/] to fetch compile-time dependencies. Ivy needs to be able to access the web servers that host the dependencies (typically maven repositories). If your internet access is proxied, ivy (ant, really) needs to know about it. There are two ways to accomplish this:

Got Git?

Branch-specific Git repo

Sometimes it's necessary to create an entirely new repository instance to work on a branch (for example, if you need to work in a separate IDE configuration). This is particularly common in the long-term support of stable releases. The following recipe can be used to create a Git repository for tracking/committing to/from a single branch.

mkdir cassandra-0.7
cd cassandra-0.7
git init
git remote add -f -t cassandra-0.7 -m master origin git://github.com/apache/cassandra.git

git remote set-head origin cassandra-0.7
git merge origin

# Git-svn setup
cd .git; wget http://git.apache.org/authors.txt; cd ..
git config svn.authorsfile ".git/authors.txt"
git svn init --prefix=origin/ --branches=branches https://svn.apache.org/repos/asf/cassandra

Committing

Got commit access? Outstanding! Here are the conventions we follow.

Commit messages take the form of

<explanation>

patch by <author>; reviewed by <committer> for CASSANDRA-<ticket>

When committing to multiple branches, start with the most-stable and merge forwards. For instance, if you had a fix to apply to 1.1, 1.2, and trunk, you would first commit to 1.1, and push changes. Then, switch to your 1.2 branch by doing

    git checkout cassandra-1.2

    git merge cassandra-1.2

If there are conflicts, resolve them and commit, followed by a push. Finally, switch to trunk by doing

    git checkout trunk

and run

    git merge cassandra-1.2

again resolve conflicts if the exist, and commit and push.

See http://www.youtube.com/watch?v=AJ-CpGsCpM0 for an in-depth explanation of why fixes should be merged forwards from more-stable branches, rather than backported from trunk.

This workflow also makes it so git knows what commits have been made to earlier branches but not to trunk: if you forget to merge a fix immediately, the next time someone goes to merge from the branch, git will incorporate the forgotten ones too.

stats

HowToContribute (last edited 2014-04-10 20:00:58 by TylerHobbs)