cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Cassandra Wiki] Update of "HowToContribute" by JoelKnighton
Date Thu, 10 Dec 2015 19:51:48 GMT
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.

Mime
View raw message