Branching and Pull Requests for Code Review
Using branches for code review
We have consistently advised against using Git branches in 6.102. However…
In the wider world of software engineering, changes are usually subjected to code review before they are committed to the main branch that everyone is developing on, not after. Let’s see how that works for one popular Git-based collaboration tool: GitHub.
On GitHub, a reviewable set of changes to the project is called a pull request, frequently abbreviated PR, because you are requesting that the maintainers of the project pull your suggested changes into the code. When you are one of those maintainers yourself, you can create and use pull requests by creating branches:
Create a new local branch and commit your changes on that branch
Push that local branch to a remote branch of the same name (just as we have been pushing and pulling local
main
and remotemain
)Point reviewers at the PR, where they can add general or line-specific comments
Respond to requested changes by making further commits on your local branch and pushing them remotely, which updates the PR
Finally, use the GitHub UI to merge the reviewed changes onto the
main
branch, which closes the pull request and merges the code without having to run localgit
commands.
We don’t recommend using pull requests for every change in your 6.102 project, but if everyone on the team wants to try this process, you might use it for major “iter1” or later changes. Don’t use pull requests for “iter0” because the purpose of iter0 is quick prototypes, not careful review.
And in case there was any doubt: for a project of this size and scope, don’t over-rely on process, focus on clear communication and frequent syncing-up of the whole team.
Team warmup exercise
If all the members of your team feel confident about trying Git branches and GitHub pull requests for code review on the project, use the following exercise as a group warmup to practice the procedure and decide how you want to use GitHub’s features.
You should do this exercise together in person. Make sure everyone has completed each step before moving on together to the next step.
Step 0: create an exercise repo
One member of the group: ask Didit to create a warmup exercise repo.
After the repo is created: everyone should go to Didit, clone the warmup repo, cd
into into it, npm install
, and continue below.
Step 1: propose a change on a branch
Switch to a branch called warmup-«your username»
.
The command for this is:
git switch -c warmup-USERNAME
← create a new branch and switch to it
Run git status
to see that you are on that branch.
Open src/«your username».ts
and update the greeting
constant.
Save, add, commit, and push to your branch.
The push command is:
git push -u origin warmup-USERNAME
← push a branch to the origin remote when it was not there before
When you push, github.mit.edu
will suggest in the console output the URL you can visit to create a pull request!
On github.mit.edu
, create a pull request asking to merge your change from branch warmup-«your username»
onto branch main
.
Go to the tab listing open pull requests and wait until everyone has created their request.
Step 2: practice merging on main
Switch back to branch main
, and see that your changes in «your username».ts
are no longer in your working copy!
The command for this is:
git switch main
← switch to an existing branch without creating it
Open main.ts
and un-comment your two lines only.
Add and commit locally, making sure to commit on branch main
.
Once everyone has committed: push, pull and merge all the changes! Make sure everyone reaches the same local SHA with a clean working copy.
At this point, npm run main
should output three lines of MISSING
.
Make sure everyone understands why!
Step 3: code review
With everyone on main
, the same local SHA, and a clean working copy…
Assign each person’s pull request to a different team member. You could do this formally by assigning “reviewers” in the GitHub UI, or just verbally.
Visit that assigned PR and ask for a change: e.g., “please use more exclamation points!!!”. GitHub provides multiple ways to do this, including an unstructured “conversation” tab and line-specific comments on the “files changed” tab.
Step 4: address code reviews
Now visit the page for your own PR and see what was requested of you.
Switch back to your local warmup-«your username»
branch.
See that the changes in main.ts
are no longer in your working copy!
Make the change requested by your reviewer.
Add, commit, and push on branch warmup-«your username»
.
View your pull request on github.mit.edu
and see that it is updated.