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 indicating that you agree to the CCLA, also send it 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).
• 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.hbase.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.