How to Contribute

This document contains advice about developing patches for Flume.

This document will be updated as more infrastructure is put in place.

Getting the source

Check out the code using SVN. The repository's root lives here. Most development happens under the 'trunk' so this command line can be used.

svn co http://svn.apache.org/repos/asf/incubator/flume/trunk flume-trunk

Alternately if you prefer using git

git clone git://git.apache.org/flume

Contributing changes

Before you start, describe your proposed changes and check that they fit in with what others are doing and have planned for the project. Be patient, it may take folks a while to understand your requirements. This can be done by
- sending a message to the <dev-flume AT SPAMFREE incubator DOT apache DOT org> Flume developer mailing list,
- filing a bug report in Flume issue tracker JIRA, or
Alternately, if you are interested in contributing you can find an existing issue one to work on. If you are just starting, we'd suggest you pick an "Easy" issue

Assign the issue to yourself in the JIRA. If you cannot, ask one of the project administrators to add you as a contributor.
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 patch.
Create a patch with your changes and commit message information. You can use svn stat to see which file have been modified, svn add to add the files for commit, and then svn diff > FLUME-###.patch to generate a patchfile.
Post patch to Reviewboard for code review. (see below)
Upload patch to JIRA granting license to Apache and put link to specific code review to the in the comments.
Update the issue in JIRA to reflect status "patch available".
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":http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html 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.
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.)
    }
  }
}

Reviewboard

We use reviewboard for code reviews. It is highly encouraged for all patches – patches submitted to reviewboard are easier to review and comment on. Our reviewboard server is at http://reviews.apache.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 patch base path should usually be /
- 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 JIRA issue number (e.g., "FLUME-10") in the "bugs" list.
- Make sure to hit "Publish" when you're ready.

Instructions for Committers

TODO

Child pages