HowToContribute

This document contains advice about developing patches for Flume.

Here’s the basic steps:

• Create an issue on the JIRA issue tracker describing your feature/bug report (or find an existing one to work on)
• Check out the code with git clone git://github.com/cloudera/flume.git
• Make your changes. These should include unit tests. Big changes should be discussed ahead of time, some up front design documentation may be necessary.
• Make sure your changes pass the required code quality metrics (see below)
• Create a single commit containing all your changes and a descriptive commit message (what files/classes did you add/remove; what tests did you add; what functionality does this include; etc). If you made multiple commits during your development process, squash them down to a single commit object with git rebase.
• Create a patch with your changes and commit message information: git format-patch -1 HEAD, attach the patch to the JIRA and indicate that you agree to the CCLA by including “I grant license to Cloudera for inclusion in Cloudera works (as per the Apache License §5)” as a comment, or (better yet!) by faxing the form to us so that we can have it on file. Then send the patch to Reviewboard (see further below)
• Update the issue in JIRA to reflect status “patch available” and put a link to the Reviewboard review in the comments.
• Iterate with revised changes, etc.
• When it’s ready, a committer will push it to the repository and mark the issue as “Resolved/Fixed” in JIRA.

Code Quality

Code added to Flume should meet the following code quality metrics:

• Findbugs should pass with zero warnings. See COMPILING.txt (in the root of the source repository) for instructions on running Findbugs.
• All existing unit tests must pass. New unit tests must be added for all non-trivial improvements.
• Public classes, methods, constants, etc. must have Javadoc comments. Additional Javadoc comments are encouraged.
• Code should be formatted according to the Java Code Conventions with the following exceptions:
  • All whitespace should be spaces (no tabs).
  • Indent by two spaces
  • All files must start with the Apache license header block (see any existing source file).
• No gratuitous reformatting of code please.
• To verify that you’re writing code with the correct style, run the checkstyle target and look at its output. (See COMPILING.txt for more details.) You should not introduce additional checkstyle warnings.
• Please fix any “broken windows” in your neighborhood. If you’re modifying an existing method that does not comply with these standards, please update the method.

/** Holds some example code formatting. */
class ExampleClass {
  /** Does some thing.
   * @param someArg you are encouraged to document arguments with @param.
   * @returns is also an encouraged metadata tag in public methods.
   */
  public void someMethod(int someArg) {
    // Note two spaces indenting each time. No tabs!
    someMethodCall(this, has, many,
        args); // Four space indent here.
    if (someCondition) {
      // Use a space after 'if' and before '('.
      // Use complete sentences in comments.
      // Do not use /* .. */ for text comments. Only use //-comments.
    } else {
      // If and else blocks are always surrounded by { .. }.
      // (i.e., follow the One True Brace Style.)
    }
  }
}

Example code formatting

Reviewboard

We use reviewboard for code reviews. Our reviewboard server is at http://review.cloudera.org.

• Create a new account for yourself.
• Sign up for the “Flume” review group if you would like to receive email when new patches are posted. (Reviews are also posted to the flume-dev mailing list.)
• Create a new review. This requires creating a diff against the master branch and then uploading the patch.
  • The repository should be set to “flume”.
  • Add the group “flume” to the Reviewer Groups list (otherwise we won’t see it).
  • Describe your changes and the test plan you implemented and executed.
  • Put the http://issues.cloudera.org/browse/FLUME issue number (e.g., “FLUME-10”) in the “bugs” list.
  • Make sure to hit “Publish” when you’re ready.

Instructions for Committers

When someone has created a patch that you’d like to commit and passes the review guidelines above, follow these steps to commit it:

• If a patch is created with git format-patch then you should apply it with git am --signoff filename. Ensure the commit message starts with the JIRA number followed by a “.” and a short summary on the first line. e.g., FLUME-10. Fixes the foobar widget.. If this is not done, edit the commit message (git commit --amend -e) to reflect this.
• If a patch is just a regular .patch file, apply it with patch(1), git add any files as needed, and commit with git commit --author="Helpful Hacker <helpful@hacker.com>" -e; fill out a descriptive commit message in the format above, and create the commit.
• Make sure tests (ant test), findbugs (ant findbugs), checkstyle (ant checkstyle) and the release audit tool (ant releaseaudit) all pass without warnings or errors. Keep the tree green!
• Double-check the commit info (message, author, etc.) with git log -1.
• Push the results to the master branch on the cloudera/flume github project: git push your-github-remote-here master
• Mark the review on Reviewboard as submitted, and the JIRA as “Resolved/Fixed.” Add a comment to the JIRA stating that you’ve pushed this. Set the fixVersion(s) to the branches you’ve committed this to.