Repository: mesos Updated Branches: refs/heads/master c624a97d3 -> f39b39c69
Added additional details to developers guide. These two items tripped me up when trying to submit a patch. This also fixes whitespace inconsistencies (mixed tabs and spaces). Review: https://reviews.apache.org/r/30347 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/f39b39c6 Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/f39b39c6 Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/f39b39c6 Branch: refs/heads/master Commit: f39b39c69c6eaf6c18c4cd0f135f887a6532eaa0 Parents: c624a97 Author: David Robinson <[email protected]> Authored: Tue Jan 27 17:35:28 2015 -0800 Committer: Benjamin Mahler <[email protected]> Committed: Tue Jan 27 17:40:00 2015 -0800 ---------------------------------------------------------------------- docs/mesos-developers-guide.md | 66 +++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 32 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/f39b39c6/docs/mesos-developers-guide.md ---------------------------------------------------------------------- diff --git a/docs/mesos-developers-guide.md b/docs/mesos-developers-guide.md index 036a6fd..0a30587 100644 --- a/docs/mesos-developers-guide.md +++ b/docs/mesos-developers-guide.md @@ -18,55 +18,57 @@ layout: documentation ### Before you submit 1. Check out the code from the Apache repository via Git. Instructions are on the [Getting Started](http://mesos.apache.org/gettingstarted/) page. -1. Join the [email protected] mailing list by sending an email to [email protected] +2. Join the [email protected] mailing list by sending an email to [email protected] -1. Find a JIRA that is currently unassigned that you want to work on at [JIRA issue tracker](https://issues.apache.org/jira/browse/MESOS), or create your own (you'll need a JIRA account for this, see below)! - 2. 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 +3. Find a JIRA that is currently unassigned that you want to work on at [JIRA issue tracker](https://issues.apache.org/jira/browse/MESOS), or create your own (you'll need a JIRA account for this, see below)! + 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 -1. Assign the JIRA to yourself. To do this, you will need: - 2. An Apache JIRA user account (sign up for one [here](https://issues.apache.org/jira/secure/Signup!default.jspa)) +4. Assign the JIRA to yourself. To do this, you will need: + 1. An Apache JIRA user account (sign up for one [here](https://issues.apache.org/jira/secure/Signup!default.jspa)) 2. You need to be added to the list of Mesos "contributors" by a Mesos committer (send email to [email protected]) in order to be assigned (or to assign yourself) to a JIRA issue -1. Formulate a plan for resolving the issue, propose your plan via comments in the JIRA +5. Formulate a plan for resolving the issue, propose your plan via comments in the JIRA -1. Create one or more test cases to exercise the bug or the feature (the Mesos team uses [test-driven development](http://en.wikipedia.org/wiki/Test-driven_development)), before you start coding, make sure these test cases all fail. +6. Create one or more test cases to exercise the bug or the feature (the Mesos team uses [test-driven development](http://en.wikipedia.org/wiki/Test-driven_development)), before you start coding, make sure these test cases all fail. -1. Make your changes to the code (using whatever IDE/editor you choose) to actually fix the bug or implement the feature. - 2. Before beginning, please read the [Mesos C++ Style Guide](mesos-c++-style-guide.md). It is recommended to use the git pre-commit hook (`support/hooks/pre-commit`) to automatically check for style errors. See the hook script for instructions to enable it. +7. Make your changes to the code (using whatever IDE/editor you choose) to actually fix the bug or implement the feature. + 1. Before beginning, please read the [Mesos C++ Style Guide](mesos-c++-style-guide.md). It is recommended to use the git pre-commit hook (`support/hooks/pre-commit`) to automatically check for style errors. See the hook script for instructions to enable it. 2. Most of your changes will probably be to files inside of `BASE_MESOS_DIR` - 2. To build, we recommend that you don't build inside of the src directory. We recommend you do the following: - 3. From inside of the root Mesos directory: `mkdir build && cd build` - 3. `../configure` + 3. To build, we recommend that you don't build inside of the src directory. We recommend you do the following: + 1. From inside of the root Mesos directory: `mkdir build && cd build` + 2. `../configure` 3. `make` - 3. Now all of the files generated by the build process will be contained in the build directory you created, instead of being spread throughout the src directory, which is a bit messier. This is both cleaner, and makes it easy to clean up if you want to get rid of the files generated by `configure` and `make`. I.e. You can reset your build process without risking changes you made in the src directory, by simply deleting the build directory, and creating a new one. + 4. Now all of the files generated by the build process will be contained in the build directory you created, instead of being spread throughout the src directory, which is a bit messier. This is both cleaner, and makes it easy to clean up if you want to get rid of the files generated by `configure` and `make`. I.e. You can reset your build process without risking changes you made in the src directory, by simply deleting the build directory, and creating a new one. -1. Make sure all of your test cases now pass. - 2. `make check` +8. Make sure all of your test cases now pass. + 1. `make check` -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. +9. 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 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) + 1. 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 issue id (e.g. MESOS-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 Mesos developer via Review Board, address their feedback and upload updated patches until you receive a "Ship It" from a Mesos committer. + 3. First, install post-review. [See Instructions](http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/) + 4. Configure post-review. The easiest method is to symlink to the sample config: ln -s support/reviewboardrc .reviewboardrc + 5. From your local branch run `support/post-reviews.py`. + 6. Note that `post-reviews.py` creates a new review for every commit on your branch that is different from the `master`. + 7. Be sure to add your JIRA issue id (e.g. MESOS-01) to the field labeled "Bugs" (this will automatically link) + 8. 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?) + +2. Wait for a code review from another Mesos developer via Review Board, address their feedback and upload updated patches until you receive a "Ship It" from a Mesos committer. + 1. When addressing feedback, adjust your existing commit(s) instead of creating new commits, otherwise `post-reviews.py` will create a new review (`git rebase -i` is your friend). 2. 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. - 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. + 3. 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. + 4. 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! +3. 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. +4. 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. ## Style Guides * For patches to the core, we ask that you follow the [Mesos C++ Style Guide](mesos-c++-style-guide.md)
