This captures committer-specific information beyond what's covered in the contributions guide.
Accepting Pull Requests on GitHub
The ASF INFRA team maintains a mirror of our git repository over on GitHub.That mirror is strictly one-way: changes from the Apache git get copied over, but not the other way around. Further, the mirror on GitHub is read-only for everyone. Which means we can neither accept nor close pull requests filled there via the GitHub web UI. However, we want to allow for contributions via GitHub Pull Requests. Here's how:
0. Add the ASF git repository
$ git remote add apache git://git.apache.org/incubator-reef.git
As a result, you can refer to the ASF git as "apache". An example setup, with a the GitHub mirror at upstream and a forked GitHub origin at {username}:
$ git remote -v apache git://git.apache.org/incubator-reef.git (fetch) apache git://git.apache.org/incubator-reef.git (push) origin https://github.com/{username}/incubator-reef.git (fetch) origin https://github.com/{username}/incubator-reef.git (push) upstream https://github.com/apache/incubator-reef.git (fetch) upstream https://github.com/apache/incubator-reef.git (push)
1. Create a branch on your local git repository
You want to make sure that that branch is current with the the master branch on Apache git:
$ git checkout -b BRANCH_NAME $ git pull apache master
This assumes that you called the remote git repository at the ASF "apache". You can name the branch however you want, but it is customary to name them either after the pull request number or the JIRA id, e.g. REEF-24.
2. Pull the contribution into that branch
This is as simple as
$ git pull GIT_REPOSITORY_OF_THE_CONTRIBUTOR BRANCH_NAME_OF_THE_CONTRIBUTION
However, the GitHub web ui makes it somewhat hard to get these two strings. The email from GitHub that informs us of Pull Requests makes this really obvious, though. Consider this quote from pull request #10:
You can merge this Pull Request by running
git pull https://github.com/jwang98052/incubator-reef juwang-logfactory
This copies the changes from the given remote branch into the one we just created locally.
3. Check the pull request
- Make sure the code compiles and all tests pass.
- If the code touches code that you suspect might break on YARN or Mesos, please test on those environments. If you don't have access to a test environment, ask on the mailing list for help.
- Make sure the code adheres to our coding guidelines.
4. Rebase the branch onto current apache master
# Make sure we have the latest bits $ git fetch apache # Rebase $ git rebase -i apache/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.
Also, please make sure that the commit message contains (in addition to the original and edited comments):
- A link to the JIRA this is addressing.
- The name and email of the original contributor (e.g., Contributed by John Doe <johndoe@apache.org>).
- The text "closes #PRNUMBER", where PRNUMBER is the number of the pull request, e.g. "10"
Following the last statement will close the GitHub pull request. It is important to close via the commit message, because we cannot close pull requests via the GitHub Web UI.
5. Push the code into apache's git
This is a good time to reflect back on this change and whether it is likely to break the build. If you are certain that it won't, go ahead and do:
$ git checkout master $ git merge BRANCH_NAME $ git push apache master
This pushes the current branch into the master branch hosted on Apache's git repository. From there, it will be mirrored onto GitHub. And by virtue of the comment added above to the commit message, GitHub will now close the Pull Request.