This document contains advice about developing patches for Flume.

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

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
  • subscribing and sending a message to the <dev-flume AT SPAMFREE incubator DOT apache DOT org> Flume developer mailing list.
  • getting an account and filing an issue in the Apache Flume issue tracker JIRA.
• 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. Almost all patches should include unit tests or modifications to unit tests. Big cross-cutting changes should be discussed ahead of time, some up front design documentation and consideration for backwards compatibility 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 files have been modified, svn add to add the files for commit, and then svn diff > FLUME-###.patch to generate a patchfile.
  • You can use git status to see which files have been modified, git add to add files for commit, and then git format-patch to generate a git 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, (usually formatting, correctness review as well as request for docs or follow on issues).
• 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.)
• SVN:
  • 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.

• Git:
  • 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-git".
  • 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