Page History

...

Note: This guide applies to general contributors. If you are a committer, please read the How to Commit as well.

...

...

What can be contributed?

There are many ways you can contribute towards the project. A few of these are:

...

• Attach the patches as you go through development:
  • While small fixes are easily done in a single patch, it is preferable that you attach patches to the JIRA as you go alongcreate a GitHub pull request and update it as needed. This serves as an early feedback mechanism where interested folks can look it over and suggest changes where necessary. It also ensures that if for some reason you are not able to find the time to complete the change, someone else can take up your initial patches and drive them to completion.

...

• Test your changes before submitting a review:
  • Before you make the JIRA status as "Patch Available", please test your changes thoroughly. Try any new feature or fix out for yourself, and make sure that it works.
  • Make sure that all unit/integration tests are passing, and that the functionality you have worked on is tested through existing or new tests.
  • You can run all the tests by going to the root level of the source tree and typing mvn clean install.

• How to create a patch file:
  • The preferred naming convention for Flume patches is FLUME-12345.patch, or FLUME-12345-0.patch where 12345 is the JIRA number. You might want to name successive versions of the patch something like FLUME-12345-1.patch, FLUME-12345-2.patch, etc. as you iterate on your changes based on review feedback and re-submit them.
  • The command to generate the patch is "git diff". Example:

    Code Block
    $ git diff > /path/to/FLUME-1234-0.patch

• How to apply someone else's patch file:
  • You can apply someone else's patch with the GNU patch tool. Example:

    Code Block
    $ cd ~/src/flume # or wherever you keep the root of your Flume source tree $ patch -p1 < FLUME-1234.patch

  • Contributors may variously submit patches in a couple of different formats. If you get some dialog from the patch tool asking which file you want to patch, try variously the "-p1" or "-p0" flags to patch. Without any additional arguments, git diff generates patches that are applied using patch -p1. If you use git diff --no-prefix to generate your patch, you have to apply it using patch -p0. The ReviewBoard tool understands both formats and is able to apply both types automatically.

• Submitting your patch for review:
  1. To submit a patch , attach the patch file to the JIRA and change the status of the JIRA to "Patch Available".
  2. If the change is non-trivial, please also post it for review on the Review Board. Use the Repository "flume-git" on Review Board.
  3. Link the JIRA to the Review Board review. JIRA has a feature you can use for this by going to More Actions > Link > Web Link when logged into JIRA.
  Identify a reviewer:
  1. create a pull request at GitHub. Make sure to reference the Jira issue in the PR title. 
  2. Add requested reviewers to the PR when it is ready for a
  3. When posting on review board (repository: "flume-git"), always add the Group "Flume" to the list of reviewers.
  4. Optionally, you may also add a specific reviewer to the review. You can pick any of the project committers for review. Note that identifying a reviewer does not stop others from reviewing your change. Be prepared for having your change reviewed by others at any time.
  5. If you have posted your change for review and no one has had a chance to review it yet, you can gently remind everyone by dropping a note on the developer mailing list with a link to the review.

• Work with reviewers to get your change fleshed out:
  1. When your change is reviewed, please engage with the reviewer via JIRA or review board the pull request to get necessary clarifications and work out other details.
  2. The goal is to ensure that the final state of your change is acceptable to the reviewer so that they can +1 it.

Reviewing Code

Flume uses the Apache Review Board GitHub pull requests for doing code reviews. In order for a change to be reviewed, it should be either posted on the review board or attached to the JIRA. If the change is a minor change affecting only few lines and does not seem to impact main logic of the affected sources, it need not be posted on the review board. However, if the code change is large or otherwise impacting the core logic of the affected sources, it should be posted on the review board. Feel free to comment on the JIRA requesting the assignee to post the patch for review on review board.Note: Not all patches attached to a JIRA are ready for review. Sometimes the patches are attached just to solicit early feedback regarding the implementation direction. Feel free to look it over and give your feedback in the JIRA as necessary. Patches are considered ready for review either when the patch has been posted on review board, or the JIRA status has been changed to 'Patch Available'. Find here a list of Flume JIRAs marked Patch Availablecreate a pull request..

Goals for Code Reviews

The net outcome from the review should be the same - which is to ensure the following:

...