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:

...

Review Code: If you see that a JIRA ticket has a '"Patch Available' " status, go ahead and review it. It cannot be stressed enough that you must be kind in your review and explain the rational rationale for your feedback and suggestions. Also note that not all review feedback is accepted - often times it is a compromise between the contributor and reviewer. If you are happy with the change and do not spot any major issues, then +1 it. More information on this is available in the following sections.

Provide Patches: We encourage you to assign the relevant JIRA issue to yourself and supply a patch for it. The patch you provide can be code, documentation, build changes, or any combination of these. More information on this is available in the following sections.

Reviewing Code

Flume uses the Apache Review Board 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.

Providing Patches

In order to provide patches, follow these guidelines:

• Make sure there is a JIRA:
  1. If you are working on fixing a problem that already has an associated JIRA, then go ahead and assign it to yourself.
  2. If it is already assigned to someone else, check with the current assignee before moving it over to your queue.
  3. If the current assignee has already worked out some part of the fix, suggest that you can take that change over from them and complete the remaining parts.

• Attach the patches as you go through development:
  • While small fixes are easily done in a single patch, it is preferable that you create 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.

• Before you submit your patch:
  1. Your change should be well-formatted and readable. Please use two spaces for indentation (no tabs).
  2. Carefully consider whether you have handled all boundary conditions and have provided sufficiently defensive code where necessary.
  3. Add one or more unit tests, if your change is not covered by existing automated tests.
  4. Insert javadocs and code comments where appropriate.
  5. Update the Flume User Guide (source) if your change affects the Flume config file or any user interface. Include those changes in your patch.
  6. Make sure you update the relevant developer documentation, wiki pages, etc. if your change affects the development environment.

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

• Submitting your patch for review:
  1. To submit a patch 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 review.

• Work with reviewers to get your change fleshed out:
  1. When your change is reviewed, please engage with the reviewer via JIRA or 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 GitHub pull requests for doing code reviews. Feel free to comment on the JIRA requesting the assignee to create a pull request.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'.

Goals for Code Reviews

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

...

• Test the change: It is very easy to test the change if you have the development environment setup. Run as many tests as you want with the patch. Manually test the change for functionality that you think is not fully covered via the associated tests. If you find a problem, report it.

...

If a change has met all your criteria for review, please +1 the change to indicate that you are happy with it.

Providing Patches

In order to provide patches, follow these guidelines:

...

with

...

• 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 along. 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.

• Submission checklist: Here is a checklist of things you should address before you post your patch for review:
  • Change should be clean, well-formatted, and readable. Please use two space indents, and space instead of tabs.
  • Make sure you have considered how to handle boundary condition cases and have sufficiently defensive code where necessary.
  • Add comments or java-docs where necessary.
  • Make sure that you have run checkstyle and findbugs and eliminated all warnings related to your change.
  • Is your change covered by any test case? If not, add a test case.
  • If your change affects a user interface, make sure you have updated the documentation accordingly.
  • If your change affects the development environment, make sure you update the COMPILING.txt and README files.

• Test your changes before submitting a review: Before you make the JIRA status as 'Patch Available', please test your changes thoroughly. Make sure that all tests are passing and that the functionality you have worked on is tested through existing or new tests.

• Submitting a patch: To submit a patch, first make sure that you have attached it to the JIRA and changed the status of the JIRA to 'Patch Available'. If the change is non-trivial, then please also post the patch for review on review board. The commands to generate the patch are:

  Code Block
  $ svn diff > /path/to/patch-file.patch

  or

  Code Block
  $ git diff --no-prefix > /path/to/patch-file.patch

• Identify a reviewer: When posting on review board, identify at least one reviewer. You can pick any of the project committers for review. Note that identifying a reviewer does not stop from others from reviewing your change. Be prepared for having your change reviewed by others at any time. 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.

...

it.