First things first: Welcome!
REEF is a community driven project and we always welcome new people joining us. We are inviting contributions in many forms to all parts of the project, including:
- Bug reports regarding the software, the documentation, the website, guides like this, etc
- Graphics (for instance, we don't have a logo yet)
- Documentation updates, tutorials, examples
- Code: Patches, new features, etc
The majority of this guide will discuss the contribution of code
This page should get you started if you decide to do so.
Getting started
The first step is to join the community by joining our mailing list. Also, it is probably a good idea to learn how to compile and test REEF. And once you are ready to make changes, have a look at the coding guidelines to make sure your code agrees with the rest of REEF.
Finding things to work on
At any given time, there is any number of open, unassigned issues on REEF. However, some of the items on that list might since have become outdated or such. Hence, it is always a good idea to get in touch with the rest of the community on the mailing list before getting started.
Code contribution process
While contributing to REEF, you will encounter ASF infrastructure, GitHub infrastructure, and follow ASF and REEF-specific customs.
An important part of the process comes before you start the contribution process. Most issues should first be brought up in the dev@reef.incubator.apache.org mailing list. If you haven't done so yet, subscribe to the list by sending a message to dev-subscribe@reef.incubator.apache.org. After discussion, you or one of the developers will create an Issue on ASF JIRA. Again, create an account if you don't have one. Write a succinct description of the Issue, making sure to incorporate any discussion from the mailing list.
The rest of the process takes place on GitHub: you fork your own repository, make changes, and then send a pull request to the GitHub repository. In more detail:
- Fork repository
- Create branch
- Make changes in your local machine
- Merge the master branch into your branch
- Push commits into the your remote repo (forked)
- Send a pull request
1. Fork repository
First, you need to fork the REEF repository. Go to the Github repository mirrored from ASF, and click "Fork" button. Then you will have your own repository. Clone this repository to your local machine:
$ git clone https://github.com/{your_alias}/incubator-reef.git
Then, add the apache GitHub repository as upstream:
$ git remote add upstream https://github.com/apache/incubator-reef
A correct git configuration should look similar to the following, with an origin and upstream:
$ git remote -v
origin https://github.com/{your_alias}/incubator-reef.git (fetch)
origin https://github.com/{your_alias}/incubator-reef.git (push)
upstream https://github.com/apache/incubator-reef.git (fetch)
upstream https://github.com/apache/incubator-reef.git (push)
If you have an `apache.org` email address, now is the time to configure git to use it:
$ git config user.name "My Name Here" $ git config user.email myusername@apache.org
2. Create branch
Before making changes, you have to make sure the issue to resolve (e.g. fix a bug, implement a new feature, etc) is registered in the REEF JIRA. Create a branch to address the issue on your own. The name of the branch should reference the issue, e.g., REEF-{issue_number}. You can take a look how others name their branches.
3. Make changes in your local machine
Write the code and make commits as usual. Make sure all new files contain the ASF header.
4. Merge the master branch into your branch
Before sending a pull request, you should make sure that your branch includes the latest changes in the master branch. Please run the following:
$ git fetch upstream
$ git checkout {your_branch} # Skip this step if you are already on your branch.
$ git merge upstream/master
Resolve the conflicts if exist. Test with the merged code so that it does not break the system. Then, check that Apache headers are in place where needed, by running RAT:
$ mvn apache-rat:check
Finally, as a courtesy to the merger, you can rebase to master and squash all the commits from your PR into one:
# Rebase $ git rebase -i upstream/master
In the rebase process, make sure that the contribution is squashed to a single commit. From the list of commits, "pick" the commit in the first line (the oldest), and "squash" the commits in the remaining lines:
pick 7387a49 Comment for first commit squash 3371411 Comment for second commit squash 9bf956d Comment for third commit
Chapter 3 and Chapter 7 of the Git Book contains lots of information on what this means.
5. Push commits into the your remote repo (forked)
You're almost done! Push your commits into your own repo.
$ git push origin HEAD
6. Send a pull request
It is time to send a pull request. If you do not know much about pull request, you may want to read this article.
If you go to the repository at the Github website, you can notice that "Compare & Pull request" button appears. Click the button or move into "pull request" tab if you cannot find the button.
When you create a pull request, you choose the branches to compare and merge. Choose the base as apache:master and the head {your_alias}:{branch_name}. Fill out the description with what you have done. It is a good practice to start the description with "This addresses https://issues.apache.org/jira/browse/REEF-{issue_number}"
You can push additional commits to address the feedback from the reviewer. When the status is good enough to be merged in the master branch, one of Committers will merge your work into the REEF codebase. Good job!
7. Merge the pull request (Committers only)
If you are committer, you can follow the steps in the Committer Guide to merge the pull request. Of course, you won't be merging your own pull requests. Nudge committers as needed to make sure everything gets merged correctly.
Other guides
There are other pages in this area you might be interested in: