Skip to end of metadata
Go to start of metadata

This document contains advice about developing patches for Flume.

Icon

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.

Alternately if you prefer using 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.

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

Labels
  • No labels