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

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

  2. Join the dev@mesos.apache.org mailing list by sending an email to dev-subscribe@mesos.apache.org

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

  10. git checkout master
  11. git pull
  12. git co my_branch
  13. 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!

    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. MESOS-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?)

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

  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