The Apache VCL code is maintained as a Git repository managed by ASF. That repository is mirrored to GitHub. Anyone on GitHub can fork the mirror, make changes, and submit pull requests against it. However, because the GitHub mirror of the repository is read-only, the pull requests cannot be directly merged into it. This page describes the process that must be followed to incorporate a pull request into the ASF maintained Git repository which, when done correctly, will cause the pull request on GitHub to be closed.

Because this process involves committing to the ASF maintained repository, only current committers to the project can perform all of these steps.

Remotes

First, you need to have remotes set up in your working copy for both the ASF maintained repo and the GitHub mirror. You can view your remotes with

git remote -v

If you don't already have both remotes set up, you can add them with

git remote add vcl-asf https://git-wip-us.apache.org/repos/asf/vcl.git
git remote add vcl-github https://github.com/apache/vcl.git

If you already have remotes setup, but have different names, you'll need to change the names used in the commands on this page accordingly. If you would like to rename any existing remotes, use the following command:

git remote rename <current name> <new name>

Working Copy

Next, set your working copy to be on the desired branch and ensure it is up to date.

git fetch vcl-asf
git checkout <branch>
git pull vcl-asf

Grab Pull Request

The following command will grab the pull request into a new branch in your working copy. NUMBER represents the number of the pull request.

git fetch vcl-github pull/NUMBER/head:pr/NUMBER

If you will be working with a number of pull requests, you may want to issue the following configuration change to simplify things.

git config --add remote.vcl-github.fetch '+refs/pull/*/head:refs/remotes/vcl-github/pr/*'

After that, you can run the following two commands, which are a little easier to remember.

git fetch vcl-github
git checkout pr/NUMBER

View Changes

To view a diff of the changes between the branch you currently have checked out and the new one created from the pull request, use git diff:

git diff pr/NUMBER

Merge Changes

Use the following command to merge the pull request. NOTE: The "--no-ff" argument and the comments are important. The phrase "This closes #NUMBER" must be included in the comment to cause the pull request to be closed on GitHub. Also, if a JIRA issue is associated with the work, the issue number (VCL-###) needs to be included in the comment.

git merge --no-ff -m "VCL-## - This closes #NUMBER" pr/NUMBER

For example, to handle PR#2 that addresses VCL-1101, the following would be used:

git merge --no-ff -m "VCL-1101 - This closes #2" pr/2

Push Changes to ASF

Optionally, diff the changes against the ASF repo to double check before pushing to it. <branch> should be the same branch that was checked out in the Working Copy section above.

git diff vcl-asf/<branch>

Finally, push the merge result to the ASF repo. This is the step that actually makes changes to the ASF repo and requires committer rights. Again, <branch> should be the same branch that was checked out in the Working Copy section above.

git push vcl-asf <branch>
  • No labels