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

  1. Check out the code from the Apache repository via Git. Instructions are on the Getting Started page.

  2. Join the dev, issues, reviews and builds mailing lists by sending emails to dev-subscribe@mesos.apache.org, issues-subscribe@mesos.apache.org, reviews-subscribe@mesos.apache.org and builds-subscribe@mesos.apache.org respectively.

  3. 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)!

    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.

  4. Assign the JIRA to yourself. To do this, you will need:

    1. An Apache JIRA user account (sign up for one here).
    2. 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.

  5. Formulate a plan for resolving the issue, propose your plan via comments in the JIRA.

  6. 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.

  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. 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
    3. From inside of the root Mesos directory: ./bootstrap (Only required if building from git repository).
    4. 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
      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.

  8. Make sure all of your test cases now pass.

    1. make check

  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 checkout 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 git rebase master to bring your branch up to date with master.

Submit your patch

  1. 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 RBTools. See Instructions
    4. Configure post-review. The easiest method is to symlink to the sample config: ln -s support/reviewboardrc .reviewboardrc
    5. Log into Review Board from the command line: run rbt status
    6. From your local branch run support/post-reviews.py.
    7. Note that post-reviews.py creates a new review for every commit on your branch that is different from the master.
    8. Be sure to add your JIRA issue id (e.g. MESOS-01) to the field labeled "Bugs" (this will automatically link)
    9. Under "Description" in addition to details about your changes, include a description of any documentation pages that 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.
    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.

  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!

  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