While adding a new script to our Python for IBM i Examples GitHub Repository, I noticed that my pull request had evolved into a near-perfect example of how tools like GitHub improve upon ordinary Git.
Standard Git provides source control; GitHub adds collaborative web-based tools that spark discussion and encourage team cooperation.
Let’s go step-by-step through the lifecycle of a pull request (known to developers as a “PR”) to illustrate what makes GitHub so great for collaboration.
My Pull Request, with Best Practices
This screenshot shows my initial comment and commits of the PR. I’ve circled the merged branches and initial commits. I named the branch in a “semantic” manner, which is my way of saying I adopted a convention of prefixing branch names with a descriptive name such as “new-script,” “hotfix,” “feature,” or “bug.”
As for naming the PR itself, I made sure to title it a “WIP”, a standard designation standing for “Work In Progress.” I included the “WIP” to let others know that this PR should not be merged until it is complete, because I planned to add more commits to this PR. (Some tools, such as GitLab, go so far as to automatically prevent anyone from merging a pull request that has “WIP” in the title until the “WIP” string is removed.)
Time to Collaborate!
Kevin Adler, a software engineer with IBM Rochester, was kind enough to review the code in my PR. Kevin used GitHub’s code-review mechanism to view my committed code and then provide comments on specific lines of code. If I’d wanted to, I could have assigned particular reviewers to the PR, tasking them with the job of reviewing the code. Once a commit has been made that affects the reviewed snippet of code, GitHub will update the code review. In this case, because I had already made updates to these reviews, GitHub shows the reviews as outdated.
Improvements from Peer Feedback
After taking Kevin’s reviews into consideration and deciding they all had merit, I made the recommended changes and committed them to the new-script/httpcrtsrv branch and pushed them out to GitHub . Remember that anything committed to the branch in the PR will update the PR. In the above screenshot, we can see that my commits and the comments are shown in order within the PR. If you read further in the PR, you’ll see that Kevin continued to review, and the code was continuously improved throughout the cycle until the PR was ready. Keep in mind that anyone with permission could be making these commits, and they’ll update the PR as well.
GitHub saves me time: when I mention PRs, commits, issues, etc., within comments, GitHub will automatically handle any relationships. Examples: one could close an issue with a PR, reference PRs within issues, close issues from within commit messages, and much more. There are even ways to integrate with other tools like Jira, and close issues this way.
Extend Git with GitHub
Features such as Visual PRs and Issues provide a shared space in which healthy team collaboration can grow. While Git itself is essential, user interfaces like GitHub provide another layer of useful tools to extend Git.