How To Contribute

Reporting a Bug

Getting your ReviewBoard Account

You’ve found a bug and want to report it. THANKS!
We track all issues via Apache’s hosted JIRA issue tracker, so if you don’t already have an account you’ll need to register for one. It’s quick and easy.
A JIRA should be created for every task, feature, bug-fix, etc. This makes it easy to track track progress of tickets.
Assign the JIRA issue to yourself before you start working on it. This helps to avoid duplication of work, and alerts anyone who is following that issue.

- -

Submitting a patch

- -

You’ve fixed a bug or added a feature and want to contribute it. AWESOME!
We use Apache Review Board for code reviews. If you don’t already have an account, you’ll need to create one (it’s separate from your Apache JIRA account).
A code review request should be created for every JIRA that involves a change to the codebase.

- -

Before you submit

- -

Check out the code from the Apache repository via Git. Instructions are on the Getting Started page.
Join the dev@aurora.incubator.apache.org mailing list by sending an email to dev-subscribe@aurora.incubator.apache.org
Find a JIRA that is currently unassigned that you want to work on at http://issues.apache.org/jira/browse/AURORA, or create your own.
- -
1. This could be a JIRA representing a bug (possibly a bug that you encountered and reported, e.g. when trying to build) or a new feature
Formulate a plan for resolving the issue, propose your plan via comments in the JIRA
Create one or more test cases to exercise the bug or the feature (the Aurora team uses test-driven development).
Make sure to pull in any changes that have been committed to master branch. Using Git, do this via something like:
- -
1. git checkout master
2. git pull
3. git co my_branch
4. Check the output of git diff master and make sure it lists only your changes. If other changes you did not make are listed, try a rebase to bring your branch up to date with master.

- -

Submit your patch

- -

You’re ready to submit your patch for review!
- -
1. Log in or create an account at Apache Review Board
2. The easiest (and recommended) way to submit reviews is through post-reviews.py a wrapper around post-review.
3. First, install post-review. See Instructions
4. From your local branch run support/post-reviews.py.
5. Note that post-reviews.py creates a new review for every commit on your branch that is different from the master.
6. Be sure to add your JIRA issue id (e.g. AURORA-01) to the field labeled “Bugs” (this will automatically link)
7. Under “Description” in addition to details about your changes, include a description of any wiki documentation pages need to be added, or are affected by your changes (e.g. did you change or add any configuration options/flags? Did you add a new binary?)
Wait for a code review from another Apache Aurora developer via Review Board, address their feedback and upload updated patches until you receive a “Ship It” from a Aurora committer.
- -
1. Review Board comments should be used for code-specific discussions, and JIRA comments for bigger-picture design discussions.
2. Always respond to each RB comment that you address directly (i.e. each comment can be responded to directly) with either “Done.” or a comment explaining how you addressed it.
3. If an issue has been raised in the review, please resolve the issue as “Fixed” or “Dropped”. If “Dropped” please add a comment explaining the reason. Also, if your fix warrants a comment (e.g., fixed differently than suggested by the reviewer) please add a comment.
After consensus is reached on your JIRA/patch, you’re review request will receive a “Ship It!” from a committer, and then a committer will commit your patch to the git repository. Congratulations and thanks for participating in our community!
The last step is to ensure that the necessary documentation gets created or updated so the whole world knows about your new feature or bug fix.

Go to https://reviews.apache.org and create an account.

Setting up your ReviewBoard Environment

+ +

Run ./rbt status. The first time this runs it will bootstrap and you will be asked to login. +Subsequent runs will cache your login credentials.

+ +

Submitting a Patch for Review

+ +

Post a review with rbt, fill out the fields in your browser and hit Publish.

./rbt post -o -g
+

Updating an Existing Review

+ +

Incorporate review feedback, make some more commits, update your existing review, fill out the +fields in your browser and hit Publish.

./rbt post -o -r <RB_ID>
+

Merging Your Own Review (Committers)

+ +

Once you have shipits from the right committers, merge your changes in a single commit and mark +the review as submitted. The typical workflow is:

git checkout master
+git pull origin master
+./rbt patch -c <RB_ID>  # Verify the automatically-generated commit message looks sane,
+                        # editing if necessary.
+git show master         # Verify everything looks sane
+git push origin master
+./rbt close <RB_ID>
+

Note that even if you’re developing using feature branches you will not use git merge - each +commit will be an atomic change accompanied by a ReviewBoard entry.

+ +

Merging Someone Else’s Review

+ +

Sometimes you’ll need to merge someone else’s RB. The typical workflow for this is

git checkout master
+git pull origin master
+./rbt patch -c <RB_ID>
+git show master  # Verify everything looks sane, author is correct
+git push origin master
+

Modified: incubator/aurora/site/source/docs/howtocontribute.html.md URL: http://svn.apache.org/viewvc/incubator/aurora/site/source/docs/howtocontribute.html.md?rev=1556043&r1=1556042&r2=1556043&view=diff ============================================================================== --- incubator/aurora/site/source/docs/howtocontribute.html.md (original) +++ incubator/aurora/site/source/docs/howtocontribute.html.md Mon Jan 6 21:44:19 2014 @@ -1,49 +1,50 @@ -# How To Contribute +How To Contribute +================= -## Reporting a Bug -* You've found a bug and want to report it. THANKS! -* We track all issues via Apache's hosted [JIRA issue tracker](https://issues.apache.org/jira/browse/AURORA), so if you don't already have an account you'll need to register for one. It's quick and easy. -* A JIRA should be created for every task, feature, bug-fix, etc. This makes it easy to track track progress of tickets. -* Assign the JIRA issue to yourself before you start working on it. This helps to avoid duplication of work, and alerts anyone who is following that issue. - -## Submitting a patch -* You've fixed a bug or added a feature and want to contribute it. AWESOME! -* We use [Apache Review Board](https://reviews.apache.org) for code reviews. If you don't already have an account, you'll need to create one (it's separate from your Apache JIRA account). -* A code review request should be created for every [JIRA](https://issues.apache.org/jira/browse/AURORA) that involves a change to the codebase. - -### Before you submit -1. Check out the code from the Apache repository via Git. Instructions are on the [Getting Started](/docs/gettingstarted/) page. - -1. Join the dev@aurora.incubator.apache.org mailing list by sending an email to dev-subscribe@aurora.incubator.apache.org - -1. Find a [JIRA](https://issues.apache.org/jira/browse/AURORA) that is currently unassigned that you want to work on at http://issues.apache.org/jira/browse/AURORA, or create your own. - 2. This could be a [JIRA](https://issues.apache.org/jira/browse/AURORA) representing a bug (possibly a bug that you encountered and reported, e.g. when trying to build) or a new feature - -1. Formulate a plan for resolving the issue, propose your plan via comments in the [JIRA](https://issues.apache.org/jira/browse/AURORA) - -1. Create one or more test cases to exercise the bug or the feature (the Aurora team uses [test-driven development](http://en.wikipedia.org/wiki/Test-driven_development)). - -1. Make sure to pull in any changes that have been committed to master branch. Using Git, do this via something like: - 2. `git checkout master` - 2. `git pull` - 3. `git co my_branch` - 2. Check the output of `git diff master` and make sure it lists only your changes. If other changes you did not make are listed, try a rebase to bring your branch up to date with master. - -### Submit your patch -1. You're ready to submit your patch for review! - 2. Log in or create an account at [Apache Review Board](http://reviews.apache.org) - 2. The easiest (and recommended) way to submit reviews is through `post-reviews.py` a wrapper around post-review. - 2. First, install post-review. [See Instructions](http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/) - 2. From your local branch run `support/post-reviews.py`. - 2. Note that `post-reviews.py` creates a new review for every commit on your branch that is different from the `master`. - 2. Be sure to add your [JIRA](https://issues.apache.org/jira/browse/AURORA) issue id (e.g. AURORA-01) to the field labeled "Bugs" (this will automatically link) - 2. Under "Description" in addition to details about your changes, include a description of any wiki documentation pages need to be added, or are affected by your changes (e.g. did you change or add any configuration options/flags? Did you add a new binary?) - -1. Wait for a code review from another Apache Aurora developer via [Review Board](http://reviews.apache.org), address their feedback and upload updated patches until you receive a "Ship It" from a Aurora committer. - 2. [Review Board](http://reviews.apache.org) comments should be used for code-specific discussions, and [JIRA](https://issues.apache.org/jira/browse/AURORA) comments for bigger-picture design discussions. - 2. Always respond to each RB comment that you address directly (i.e. each comment can be responded to directly) with either "Done." or a comment explaining how you addressed it. - 2. If an issue has been raised in the review, please resolve the issue as "Fixed" or "Dropped". If "Dropped" please add a comment explaining the reason. Also, if your fix warrants a comment (e.g., fixed differently than suggested by the reviewer) please add a comment. - -1. After consensus is reached on your JIRA/patch, you're review request will receive a "Ship It!" from a committer, and then a committer will commit your patch to the git repository. Congratulations and thanks for participating in our community! - -1. The last step is to ensure that the necessary documentation gets created or updated so the whole world knows about your new feature or bug fix. +Getting your ReviewBoard Account +-------------------------------- +Go to https://reviews.apache.org and create an account. + +Setting up your ReviewBoard Environment +--------------------------------------- +Run `./rbt status`. The first time this runs it will bootstrap and you will be asked to login. +Subsequent runs will cache your login credentials. + +Submitting a Patch for Review +----------------------------- +Post a review with `rbt`, fill out the fields in your browser and hit Publish. + + ./rbt post -o -g + +Updating an Existing Review +--------------------------- +Incorporate review feedback, make some more commits, update your existing review, fill out the +fields in your browser and hit Publish. + + ./rbt post -o -r + +Merging Your Own Review (Committers) +------------------------------------ +Once you have shipits from the right committers, merge your changes in a single commit and mark +the review as submitted. The typical workflow is: + + git checkout master + git pull origin master + ./rbt patch -c # Verify the automatically-generated commit message looks sane, + # editing if necessary. + git show master # Verify everything looks sane + git push origin master + ./rbt close + +Note that even if you're developing using feature branches you will not use `git merge` - each +commit will be an atomic change accompanied by a ReviewBoard entry. + +Merging Someone Else's Review +----------------------------- +Sometimes you'll need to merge someone else's RB. The typical workflow for this is + + git checkout master + git pull origin master + ./rbt patch -c + git show master # Verify everything looks sane, author is correct + git push origin master \ No newline at end of file