Dear Wiki user, You have subscribed to a wiki page or wiki category on "Cassandra Wiki" for change notification.
The "HowToContribute" page has been changed by JoelKnighton: https://wiki.apache.org/cassandra/HowToContribute?action=diff&rev1=65&rev2=66 == Overview == 1. Pick an issue to work on. If you don't have a specific [[http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s02.html|itch to scratch]], some possibilities are marked with [[https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+=+12310865+AND+labels+=+lhf+AND+status+!=+resolved|the low-hanging fruit label]] in JIRA. - 1. Read the relevant parts of ArchitectureInternals; watching http://www.youtube.com/watch?v=W6e8_IcgJM4 will probably also be useful + 2. Read the relevant parts of [[ArchitectureInternals|Architecture Internals]]; other resources include the following videos: [[http://www.datastax.com/dev/blog/deep-into-cassandra-internals|DataStax Deep Dives into Apache Cassandra internals]], [[https://www.youtube.com/user/PlanetCassandra|Planet Cassandra videos]] such as [[https://www.youtube.com/watch?v=W6e8_IcgJM4|this Summit 2013 talk]], and Cassandra user group videos like [[https://www.youtube.com/watch?v=9Id5me7QFHU|this one from Austin Cassandra]]. - 1. Check if someone else has already begun work on the change you have in mind in the [[https://issues.apache.org/jira/browse/CASSANDRA|issue tracker]] + 3. Check if someone else has already created an ticket for the change you have in mind in the [[https://issues.apache.org/jira/browse/CASSANDRA|issue tracker]]. - 1. If not, create a ticket describing the change you're proposing in the issue tracker + 4. If not, create a ticket describing the change you're proposing in the issue tracker. + 5. When you're ready to start working on the ticket, if it has not yet been assigned, assign the ticket to yourself in JIRA. This is done using the "Assign button" at the top of the ticket. - 1. Check out the latest version of the source code + 6. Clone the latest version of the source code: - * git clone http://git-wip-us.apache.org/repos/asf/cassandra.git cassandra-trunk + * `git clone http://git-wip-us.apache.org/repos/asf/cassandra.git cassandra` + You'll want to checkout out the branch corresponding to the lowest version in which you want to introduce the change. For example, + * `git checkout cassandra-3.0` + From there, create a branch for your changes. Many contributors name their branches based on ticket number and Cassandra version. + * `git checkout -b 12345-3.0` - 1. Modify the source to include the improvement/bugfix + 7. 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 using the commands below. 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://cassci.datastax.com|CI]] results for the relevant upstream version. - * 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 + * For testing multi-node behavior, [[https://github.com/pcmanus/ccm|CCM]], a tool to easily create local clusters, is useful. - * Consider going through the [[HowToReview|Review Checklist]] for your code + * Consider going through the [[HowToReview|Review Checklist]] for your code. This will help you to understand how others will consider your change for inclusion. - 1. When you're happy with the result create a patch: + 8. When you're happy with the result, create a patch: - * git add <any new or modified file> + * `git add <any new or modified file>` - * git commit -m '<message>' + * `git commit -m '<message>'` - * git format-patch + * `git format-patch` - * mv <patch-file> <branchname-issue.txt> (e.g. trunk-123.txt, cassandra-0.6-123.txt) - 1. Attach the newly generated patch to the issue and click "Submit patch" in the left side of the JIRA page - 1. Wait for other developers or committers to review it and hopefully +1 the ticket (see [[HowToReview|How To Review]]) - 1. Wait for a committer to commit it. + * `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: + * `git push --set-upstream origin 12345-3.0` + 9. 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. + 10. 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. + 11. Wait for other developers or committers to review it and hopefully +1 the ticket (see [[HowToReview|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. + 12. If the reviewer has given feedback to improve the patch, make the necessary changes and move the ticket into "Patch Available" once again. + 13. Once the review process is complete, you will receive a +1. Wait for a committer to commit it. == Testing and Coverage == - Setting up and running system tests: + There are two major sets of tests for Cassandra: unit tests and dtests. The unit tests are part of the Cassandra repository; dtests are functional tests that are available at [[https://github.com/riptano/cassandra-dtest]]. === Running the Unit Tests === - Simply run `ant test` to run all unit tests. To run a specific test class, run `ant -Dtest.name=<ClassName>`. To run a specific test method, run `ant testsome -Dtest.name=<ClassName> -Dtest.methods=<comma-separated list of method names>`. + Run `ant test` from the top-level directory of your Cassandra checkout to run all unit tests. To run a specific test class, run `ant -Dtest.name=<ClassName>`. In this case, !ClassName should not be fully qualified. For example, it might be `StorageProxyTest`. To run a specific test method, run `ant testsome -Dtest.name=<ClassName> -Dtest.methods=<comma-separated list of method names>`. When using the `testsome` command, !ClassName should be a fully qualified name (like `org.apache.cassandra.service.StorageProxyTest`). You can also run tests in parallel: `ant test -Dtest.runners=4`. === Running the dtests === - The dtests use [[https://github.com/pcmanus/ccm|ccm]] to test a local cluster. + The dtests use [[https://github.com/pcmanus/ccm|CCM]] to test a local cluster. If the following instructions don't seem to work, you may find more current instructions in the [[https://github.com/riptano/cassandra-dtest|dtest repository]]. - 1. Install ccm. You can do this with pip by running `pip install ccm`. + 1. Install CCM. You can do this with pip by running `pip install ccm`. 1. Install nosetests. With pip, this is `pip install nose`. - 1. Install cassandra python driver. `pip install cassandra-driver` - 1. Clone the dtest repo: https://github.com/riptano/cassandra-dtest.git + 1. Install Cassandra Python driver. This can be installed using `pip install git+git://github.com/datastax/python-driver@cassandra-test`. This installs a dedicated test branch driver for new features. If you're working primarily on older versions, `pip install cassandra-test` may be sufficient. + 1. Clone the dtest repository: + * `git clone https://github.com/riptano/cassandra-dtest.git cassandra-dtest`. - 1. Set `$CASSANDRA_DIR` to the location of your cassandra checkout. For example: `export CASSANDRA_DIR=/home/joe/cassandra`. Make sure you've already built cassandra in this directory. + 1. Set `$CASSANDRA_DIR` to the location of your cassandra checkout. For example: `export CASSANDRA_DIR=/home/joe/cassandra`. Make sure you've already built Cassandra in this directory. You can build Cassandra by running `ant`. - 1. Run all tests by running `nosetests` from the dtest checkout. You can run a specific module like so: `nosetests cql_tests.py`. You can run a specific test method like this: `nosetests cql_tests.py:TestCQL.counters_test` + 1. Run all tests by running `nosetests` from the dtest checkout. You can run a specific module like so: `nosetests cql_tests.py`. You can run a specific test method like this: `nosetests cql_tests.py:TestCQL.counters_test`. === Running the code coverage task === - 1. Run a basic coverage report of unit tests using `ant codecoverage` + 1. Run a basic coverage report of unit tests using `ant codecoverage`. - 1. Alternatively, run any test task with `ant jacoco-run -Dtaskname=some_test_taskname`. Run more test tasks in this fashion to push more coverage data onto the report in progress. Then manually build the report with `ant jacoco-report` (the 'codecoverage' task shown above does this automatically). + 1. Alternatively, run any test task with `ant jacoco-run -Dtaskname=some_test_taskname`. Run more test tasks in this fashion to push more coverage data onto the report in progress. Then manually build the report with `ant jacoco-report` (the `codecoverage` task shown above does this automatically). 1. View the report at `build/jacoco/index.html`. - 1. When done, clean up jacoco data so it doesn't confuse your next coverage report: `ant jacoco-cleanup`. + 1. When done, clean up !JaCoCo data so it doesn't confuse your next coverage report: `ant jacoco-cleanup`. === Continuous integration === - Jenkins runs the Cassandra tests continuously: http://cassci.datastax.com/ (Builders for stable branches also exist.) + Jenkins runs the Cassandra tests continuously: [[http://cassci.datastax.com/]]. For frequent contributors, this Jenkins is set up to build branches from their !GitHub repositories. It is likely that your reviewer will use this Jenkins instance to run tests for your patch. == IDE == + Most Cassandra developers use an IDE. Instructions to use IntelliJ IDEA or Eclipse for Cassandra development are available. * [[RunningCassandraInIDEA]] - * RunningCassandraInEclipse + * [[RunningCassandraInEclipse]] - * IntelliJ Project Settings: - * Main Class for Thrift: org.apache.cassandra.thrift.CassandraDaemon (Used to be org.apache.cassandra.service.CassandraDaemon ) - * Main Class for Avro: org.apache.cassandra.avro.CassandraDaemon (Exprimental, introduced in 0.6) - * VM Parameters: -ea -Xmx1G -Dstorage-config=conf -Dcassandra-foreground == Committing == Got commit access? Outstanding! Here are the conventions we follow.
