This document contains advice about developing patches for Flume.
This document will be updated as more infrastructure is put in place.
Patch process
- Create an issue on the JIRA "issue tracker":https://issues.apache.org/jira/browse/FLUME
describing your feature/bug report (or find an existing one to work on)
- Check out the code TODO
- 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 TODO
- Create a patch with your changes and commit message information TODO
- 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":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. Our reviewboard server is at TODO
- 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.apache.org/jira/browse/FLUME":JIRA issue number (e.g., "FLUME-10") in the "bugs" list.
- Make sure to hit "Publish" when you're ready.
Instructions for Committers
TODO