Creating a Pull Request

Prerequisites

  • You have set up git on our system
  • You have registered a GitHub account and forked the ROOT repository
  • You have cloned your forked ROOT repository using git clone https://github.com//root

After you have cloned the repository, you will be on the master branch. Do not make changes to the master branch, as this branch will contain the newest changes in ROOT we will later pull in to our feature branch.

Making your changes

Before implementing your changes, create a new branch that we will work on in isolation from master. In this case, we will name it histogram-race-condition-fix, but you may name it differently according to what your contribution will be.

git checkout -b histogram-race-condition-fix

After implementing your changes, add and commit your changes (More about how to use git here):

git add hist/hist/somefile.cxx
git commit -m "Avoid race condition on Ubuntu 16.04"
git push --set-upstream origin histogram-race-condition-fix

Your changes are now in your forked repository on GitHub. We will now make the pull request.

Making the pull request on GitHub

Two ways:

  1. The last command,git push --set-upstream origin histogram-race-condition-fix, gives you the URL allowing to create the pull request
    ...
    remote: Create a pull request for 'histogram-race-condition-fix' on GitHub by visiting
    remote:      https://github.com/couet/root/pull/new/histogram-race-condition-fix
    ...
    

    Copy/Paste this URL in your favorite web browser.

  2. If you go to https://github.com/<your GitHub username>/root, you will see a notification saying “Your recently pushed branches: histogram-race-condition-fix (some minutes ago)”: You can now hit the green “Compare & pull request” button which lets you create the pull request.

Fill in a reasonable description of what your new feature is, and hit “Create pull request”. A project member will later initiate a build of your pull request and then review your pull request before giving feedback and in the end hopefully merge it. More about how what happens after submitting the pull request can be found in the contributing readme.

Pulling the last changes from upstream/master

Often, there might have been changes in the upstream/master repository that you want to have together with your new changes. This section will describe how to pull the new changes.

Add the ROOT repository upstream as a remote:

git remote add upstream https://github.com/root-project/root

Make sure you are on the master branch locally and pull the latest changes from upstream:

git checkout master
git pull upstream master

Go back to your local branch and rebase the last changes from master:

git checkout histogram-race-condition-fix
git rebase master

Push your new updated local branch to your GitHub repository (origin):

git push --force

Summary


The entire workflow is summarized in the image above. First, we cloned root- project/root, and cloned it to our local machine. Then after making the commit, we pushed the change to origin. Optionally, we can pull down the last changes from upstream and rebase our branch onto the current master and force-push this to origin. After this, we create a pull request on GitHub from origin. It is important to note that it is not necessary to fork and clone for each contribution.

Merging a pull request locally

If the pull request does not have any conflicts with the master branch, it is possible to apply the changes locally by downloading a patch and piping it to git am with

wget -qO- https://github.com/root-project/root/pull/<PR#>.patch | git am

If you have conflicts, the preferred method is to rebase your branch onto master:

git remote update && git checkout master && git pull && git rebase master <your branch>

When a conflict exists with a commit, git will interrupt the rebase and let you resolve them by editing your files. Once the conflict is resolved, use

git add <conflicting files> && git rebase --continue

to continue the rebasing process. After all conflicts have been resolved, you can check that your changes are really what you want with git log -p master..<your branch> then push the result (without using –force).

Resources