Developers Guide
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, 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@mesos.apache.org mailing list by sending an email to dev-subscribe@mesos.apache.org
-
Find a JIRA that is currently unassigned that you want to work on at JIRA issue tracker, or create your own (you'll need a JIRA account for this, see below)!
- 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
-
Assign the JIRA to yourself. To do this, you will need:
- An Apache JIRA user account (sign up for one here)
- You need to be added to the list of Mesos "contributors" by a Mesos committer (send email to dev@mesos.apache.org) in order to be assigned (or to assign yourself) to a JIRA issue
-
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 Mesos team uses test-driven development), before you start coding, make sure these test cases all fail.
-
Make your changes to the code (using whatever IDE/editor you choose) to actually fix the bug or implement the feature.
- Before beginning, please read the Mesos C++ Style Guide. 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. - Most of your changes will probably be to files inside of
BASE_MESOS_DIR
- To build, we recommend that you don't build inside of the src directory. We recommend you do the following:
- From inside of the root Mesos directory:
mkdir build && cd build
../configure
make
- 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
andmake
. 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.
- From inside of the root Mesos directory:
- Before beginning, please read the Mesos C++ Style Guide. It is recommended to use the git pre-commit hook (
-
Make sure all of your test cases now pass.
make check
-
Make sure to pull in any changes that have been committed to master branch. Using Git, do this via something like:
git checkout master
git pull
git co my_branch
- 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!
- Log in or create an account at Apache Review Board
- The easiest (and recommended) way to submit reviews is through
post-reviews.py
a wrapper around post-review. - First, install post-review. See Instructions
- Configure post-review. The easiest method is to symlink to the sample config: ln -s support/reviewboardrc .reviewboardrc
- From your local branch run
support/post-reviews.py
. - Note that
post-reviews.py
creates a new review for every commit on your branch that is different from themaster
. - Be sure to add your JIRA issue id (e.g. MESOS-01) to the field labeled "Bugs" (this will automatically link)
- 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 Mesos developer via Review Board, address their feedback and upload updated patches until you receive a "Ship It" from a Mesos committer.
- 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). - Review Board comments should be used for code-specific discussions, and JIRA comments for bigger-picture design discussions.
- 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.
- 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.
- When addressing feedback, adjust your existing commit(s) instead of creating new commits, otherwise
-
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.
Style Guides
- For patches to the core, we ask that you follow the Mesos C++ Style Guide