When you contribute code, you affirm that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.
Contributing by Helping Other Users
A great way to contribute to Apache Falcon is to help answer user questions on the email@example.com mailing list. There are always many new Falcon users; taking a few minutes to help answer a question is a very valuable community service.
Contributors should subscribe to this list and follow it in order to keep up to date on what's happening in Falcon. Answering questions is an excellent and visible way to help the community, which also demonstrates your expertise.
Contributing by Testing Releases
Falcon's release process is community-oriented, and members of the community can vote on new releases on the firstname.lastname@example.org mailing list. Falcon users are invited to subscribe to this list to receive release vote announcements, and test their workloads on newer release and provide feedback on any performance or correctness issues found in the newer release.
Contributing by Reviewing Changes
Changes to Falcon source code are proposed, reviewed and committed via Github (described later) at http://github.com/apache/falcon/pulls. Anyone can view and comment on active changes here. Reviewing others' changes is a good way to learn how the change process works and gain exposure to activity in various parts of the code. You can help by reviewing the changes and asking questions or pointing out issues -- as simple as typos or small issues of style.
Contributing Documentation Changes
To have us add a link to an external tutorial you wrote, simply email the developer mailing list.
To modify the built-in documentation, edit the source files in twiki format in Falcon's docs directory.
The process to propose a doc change is otherwise the same as the process for proposing code changes below. Note that changes to the site outside of docs must be handled manually by committers, since the rest of the http://falcon.apache.org/ site is versioned in svn and not in Github. In these cases, you should open a JIRA and attach path in the JIRA.
Contributing Bug Reports
Ideally, bug reports are accompanied by a proposed code change to fix the bug. This isn't always possible, as those who discover a bug may not have the experience to fix it. A bug may be reported by creating a JIRA but without creating a pull request.
Bug reports are most useful however if they include enough information to understand, isolate and ideally reproduce the bug. Simply encountering an error does not mean a bug should be reported; also, search JIRA and search and inquire on the mailing lists first. Bugs without sufficient details may take lot of time to respond or lead to lot of follow up discussions.
It is possible to propose new features as well. Ideal feature requests are accompanied by detailed use case and a desired solution.
Contributing Code Changes
All code changes should be initiated based on an issue in FALCON JIRA , so that other contributors are aware of the proposed work and have the opportunity to actively participate (through review, suggestions, etc). This also allows scoping the changes in appropriate releases. Code contributions are to be made available as a pull request corresponding to a specific JIRA created for the task. Once a pull request is created for the JIRA, the JIRA issue should be marked as "Patch available". Falcon project follows RTC (Review then commit). It is strongly recommended that large changes are broken up into smaller changes, thus making it easy for review. The patches should comply with the requirements below before they are made available for review.
Code Compliance Check List
All contributions should satisfy the following requirements before they can be given a +1 from a committer and be merged.
- Pull request shouldn't have any conflicts with the base branch.
- Jenkins build should succeed.
- All pull requests must be associated with a unique JIRA issue.
- There must be only one commit in the pull request.
- Commit message must start with issue id followed by the summary of corresponding JIRA. e.g. for a pull request corresponding to FALCON-1563 the short commit message should be as below
FALCON-1563 Old feed instances get deleted from SLA monitoring on feed update.
- Corresponding entry should be made in CHANGES.txt under the target release / master section and at top of subsection for issue type.
- Unit tests or integration tests must be added wherever applicable(generally for all changes except documentation changes)
- Project documentation corresponding to the change should be updated along with the code change.
List of open problems can be found in FALCON JIRA system. It is recommended that new contributors start with newbie issues before working their way into major bugs or features that requires deeper knowledge of the system.