Pull Requests

Note: this is a primer on the mechanical steps of making a pull request. See XGC Coding Guidelines for information on what the content of a good PR looks like.

When your code changes are ready to be merged into “master”, first update the “master” branch in your working copy from the remote repository. Make sure that “master” of the remote repo, which is a fork of the XGC parent repo, has been updated from the fork’s parent repo; if necessary, ask the fork owner to do this. The fork owner can update master in his fork with

git checkout master
git pull https://[username]@github.com/PrincetonUniversity/XGC-Devel.git master
git push origin master

Or alternatively (if you configured “upstream” as explained earlier in this document):

git fetch upstream
git checkout master
git merge upstream/master
git push origin master

If you are not the fork owner, ask the fork owner to update master of the fork; then

git checkout master
git pull origin master
git checkout [username/branch name]

Then merge “master” into your branch:

git merge master

This step will show you whether there are some conflicts that you need to resolve. After finishing the merge and resolving all conflicts, push the result of the merge to the remote repo (consider pulling first as described above):

git push origin [username/branch name]

This workflow prevents situations in which a pull request has conflicts. A pull request with conflicts cannot be merged. Then create a pull request from your branch into the “master” branch in the XGC parent repo online with the GitHub GUI by navigating to the tab “Pull Requests” and clicking “New Pull Request’. A dialog will open that lets you select the origin and the target branch/repo of the pull request (Fig. 9 and 11). Again, the pull request should be from your feature branch [username/branch name] in the fork to the branch “master” in the XGC parent repo (Fig. 11). After the pull request has been merged, the fork owner needs to update “master” in the fork from the parent repo. This prevents situations in which there are differing versions of “master” in the parent repo and the forks.

In the following dialog, you can enter a description of the changes that you want to be pulled, and you can choose reviewers for your pull request (Fig. 10). The list of reviewers should always include a repo admin who will merge the pull request after all reviewers have approved it.

Creating a pull request between branches in the same repository.

Entering a description of the changes to be pulled and choosing reviewers.

There may be situations, in which it becomes necessary to merge branches (other than “master”) inside the same fork or between different forks. This is possible with GitHub and it is highly recommended to use pull requests in these simulations.

Opening a pull request from a fork to the forks parent repository.