Tutorial 10

Pull Requests

Suppose you have two branches, master and b1 on GitHub. The master branch contains a stable codebase and b1 contains enhancements. A pull request gives you and your collaborators a way to review and comment on the changes in b1 and then when satisfied, merge the changes in b1 into master.

This tutorial starts completely from scratch. You will create new local and remote repositories.

Steps to Complete

1. Create a new (empty) repository on GitHub named, pullreq

2. Create a new local repository named pullreq, add a file foo.txt, add the text, “Homepage”, stage, commit, and push to the remote.

λ mkdir pullreq

λ cd pullreq

λ git init

λ notepad foo.txt

λ git add foo.txt

λ git commit -m "Created homepage"

λ git remote add origin git@github.com:drgap/pullreq.git

λ git push -u origin master

3. Add this line to the local foo.txt, “About Us”, stage, and commit (but do not push).

λ notepad foo.txt

λ git commit –a -m "Homepage, version 2"

4. (Read, no action required) Anytime two branches are different on GitHub, we can open a pull request. A pull request is a comparison between two branches, a base branch and a branch that is different. A pull request also contains all commits that make the base branch differ from the other branch. Once a pull request is created, collaborators can review the proposed changes (commits) and leave comments. After all collaborators are satisfied with the changes, you can merge the changes into the base branch. The approach we will take is that when we make changes locally, we will push them to a new branch on the remote. Then, we will go to GitHub and create a pull request. The command below will create a new remote branch, newRemBranch and push there.

λ git push origin HEAD:refs/heads/newRemBranch

5. Push changes to a new remote branch, ver2

λ git push origin HEAD:refs/heads/ver2

6. Pull your pullreq repository up on GitHub and verify that foo.txt on the master branch says, “Homepage”, and foo.txt on the ver2 branch says, “Homepage About Us”.

7. Display the homepage for your pullreq repository and click New pull request as shown on the right.

8. On the pull request dialog, do the following (as shown in the figure below):

a. Use the dropdown to select master branch as the base and select ver2 branch as the compare.

b. Type a title and description

c. Click Create pull request

9. The resulting display is rather large, so we examine it in pieces.

a. All pull requests are being displayed (there is only 1) as well as the title, description, and associated commits.

b. Next, we see a section that we will use later to merge the ver2 branch into master.

c. Towards the bottom we see a section where we can write a comment on the proposed changes.

10. Do the following:

a. Click the (only) commit in this pull request (noted in the figure in a from the previous step). This result is shown on the right.

b. Hover your mouse over the “Homepage” line and a “+” will appear. Click it.

c. As shown below, type a comment and then click Add single comment.

11. The result is shown on the right. As you can see the comments are shown in-line and they can be turned off.

12. Click Review changes on the right side of the window, as shown on the right, type a comment and then click Submit review.

13. (Read, no action required). As we saw on a previous step, there is also a Comment section at the bottom of the display. If desired, right now you can add a comment there and see that it is similar. Thus, we see three, very similar ways to leave a comment, review, etc. At present I don’t have any recommendations in terms of workflow – just do what seems appropriate.

14. Go back to your local repository, add “Specials” to the end of foo.txt, stage and commit and then push to the ver2 remote branch.

λ notepad foo.txt

λ git commit –a -m "Added specials"

λ git push -u origin master:ver2

15. On GitHub, display the pull request and click the “Commits” tab. Notice that the push added the most recent commit to this pull request.

At this point a collaborator (or you) could drill into the commit and comment/review or return to the “Conversation” tab and do similar things there.

16. Click the “Conversation” tab and scroll down to the Merge section as shown on the right. Click Merge pull request.

Note: the dropdown has 3 options for merging. We are using the top (default) one which keeps the commits (2 in this example) separate. The second option combines all the commits into one. The third option does a rebase which as I understand is an important technique; however, we will not consider it here.

17. The view is updated as shown on the right. Click Confirm merge.

18. The view is updated as shown below. At this point master and ver2 are the same. Many times we would delete the ver2 branch, although there could be reason to keep it or reuse it. Here, we will delete it, so click Delete branch.

19. Return to the default view for the repository by clicking pullreq. Note the following:

· There is only 1 branch now, master

· There have been 4 total commits

· There are no open pull requests. However, if we click the Pull requests tab and then click Closed we can see the pull request we just merged and closed.

20. (Read, no action required) This tutorial suggests a workflow:

a. Clone a branch (or pull changes)

b. Edit locally, committing as needed.

c. Push to a new branch on remote

d. Open a pull request

e. Allow time for collaborators to review/comment.

f. Merge

However, I’m not convinced this is the best workflow and there are a number of unanswered questions. Should person A continue to push commits to the same branch and thus an open pull request? What if the commits are very different? Suppose you have 3 commits that implement feature A and 2 commits that implement feature B. Should they all be in one pull request? I would think not and that the commits for feature B should be pushed to a separate branch and a separate pull request opened. Thus, feature A is on branch A (and associated pull request) and feature B is on branch B (and a different associated pull request). However, should this second pull request be trying to merge with branch A or master? It seems either way is opening up for more possibilities of conflicts (which we have conveniently ignored).

Similar questions arise for person B who is also a collaborator on the project – where should they push their commits?

5