What are the uses of GitHub projects

6.2 GitHub - Contributing to a project

Iteration of a pull request

At this point, the person responsible for the project can view and merge, reject or comment on the proposed change. Let's say he likes the idea but would prefer a slightly longer time with the lights off.

While this conversation can take place via email in the workflows illustrated in Chapter 5 Distributed Git, this happens online at GitHub. The project owner can review the unified diff and leave a comment by clicking on one of the lines.

Figure 92. Comment on a specific line of code in a pull request

As soon as the maintainer posts this comment, the person who opened the pull request (and everyone else watching the repository) will receive a notification. We'll adjust that again later, but if he turned on email notifications, Tony would get an email like this:

Figure 93. Comments sent as email notifications

Anyone can also leave general comments on the pull request. On the Pull Request Discussion page, we see an example of the Project Leader commenting on a line of code as well as leaving a general comment in the discussion area. You can see that the code comments are also brought into the discussion window.

Figure 94. Pull Request Discussion Page

Now the contributor can see what they need to do in order for their change to be accepted. Fortunately, it's very easy. Where you have to re-enter your data into the mailing list via email, you simply commit to the topic branch again with GitHub and push, which automatically updates the pull request. In the final pull request, you can also see that the old code comment in the updated pull request has been collapsed because it was made on a line that has since been changed.

Adding commits to an existing pull request does not trigger any further notification. After Tony has pushed his corrections, he decides to leave a comment to let the promoter know that they made the change they wanted.

Figure 95. Final pull request

A remarkable feature is that you get the "unified" diff when you click on the "Files Changed" tab in this pull request - i.e. the total aggregated difference that would be brought into your main branch if this topic branch were merged. In the sense of, it basically shows you automatically for the branch on which this pull request is based. See Chapter 5, Specifying What To Bring in, for more information on this type of diff.

GitHub also checks whether the pull request would merge properly and provides a button with which you can perform the merge on the server. This button only appears if you have write access to the repository and a trivial merge is possible. When you click on it, GitHub does a "non-fast-forward" merge, which means that even if the merge is fast-forward could, still a merge commit is created.

If you want, you can simply download the branch (pull) and merge it locally. If you merge this branch with the branch and push it to GitHub, the pull request will be closed automatically.

That's the basic workflow that most GitHub projects use. Topic branches are created, pull requests are opened, a discussion follows, another branch revision may be made, and finally the request is either closed or merged.

It's important to note that you can also open a pull request between two branches in the same repository. If you're working on a feature with someone and you both have write access to the project, you can move a topic branch to the repository and open a pull request on the branch of the same project to initiate the code review and discussion process. No forking is necessary.