Welcome contributors! We strive to include everyone's contributions. This page provides necessary guidelines on how to contribute effectively towards furthering the development and evolution of Flume. You should also read the guide on setting up Development Environment where you will find details on how to checkout, build and test Flume.
Note: This guide applies to general contributors. If you are a committer, please read the How to Commit guide as well.
There are many ways you can contribute towards the project. A few of these are:
Jump in on discussions: It is possible that someone initiates a thread on the mailing list describing a problem that you have dealt with in the past. You can help the project by chiming in on that thread and guiding that user to overcome or workaround that problem or limitation.
File Bugs: If you notice a problem and are sure it is a bug, then go ahead and file a JIRA. If however, you are not very sure that it is a bug, you should first confirm it by discussing it on the Mailing Lists.
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 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.
In order to provide patches, follow these guidelines:
Make sure there is a JIRA:
Attach the patches as you go through development:
Before you submit your patch:
Test your changes before submitting a review:
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:
$ 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:
$ 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:
Identify a reviewer:
Work with reviewers to get your change fleshed out:
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.
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 Available.
The net outcome from the review should be the same - which is to ensure the following:
Following are some guidelines on how to do a code review. You may use any other approach instead as long as the above stated goals are met. That said, here is an approach that works fine generally:
Understand the problem being solved: This often requires going through the JIRA comments and/or mailing list threads where the discussion around the problem has happened in the past. Look for key aspects of the problem such as how it has impacted the users and what, if any, is the suggested way to solve it. You may not find enough information regarding the problem in some cases, in which case - feel free to ask for clarification from the developer contributing the change.
Think about how you would solve the problem: There are many ways to solve any code problem, with different ways having different merits. Before proceeding to review the change, think through how you would solve the problem if you were the one implementing the solution. Note the various aspects of the problem that your solution might have. Some such aspects to think about are - impact on backward compatibility, overall usability of the system, any impact on performance etc.
Evaluate the proposed change in contrast to your solution: Unless the change is obvious, it is likely that the implementation of the change you are reviewing is very different from the solution you would go for. Evaluate this change on the various aspects that you evaluated your solution on in the previous step. See how it measures up and give feedback where you think it could be improved.
Look for typical pitfalls: Read through the implementation to see if: it needs to be documented at places where the intention is not clear; if all the boundary conditions are being addressed; if the code is defensive enough; if any bad idioms have leaked in such as double check locking etc. In short, check for things that a developer is likely to miss in their own code which are otherwise obvious to someone trying to read and understand the code.
See if the change is complete: Check if the change is such that it affects the user interface. If it does, then the documentation should likely be updated. What about testing - does it have enough test coverage or not? What about other aspects like license headers, copyright statements etc. How about checkstyle and findbugs - did they generate new warnings? How about compiler warnings?
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.
Once you have collected your comments/concerns/feedback you need to send it to back to the contributor. In doing so, please be as courteous as possible and ensure the following:
Once you have provided your feedback, wait for the developer to respond. It is possible that the developer may need further clarification on your feedback, in which case you should promptly provide it where necessary. In general, the dialog between the reviewer and developer should lead to finding a reasonable middle ground where key concerns are satisfied and the goals of the review have been met.
If a change has met all your criteria for review, please +1
the change
to indicate that you are happy with it.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。