Branching and Pull Requests 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 remote main)

• Use the GitHub UI to create the pull request

• 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 local git 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.

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.

One member of the group: ask Didit to create a warmup exercise repo.

Everyone else: wait!

After the repo is created: everyone should go to Didit, clone the warmup repo, cd into into it, npm install, and continue below.

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.

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!

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.

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.

Now go back to the PR where you requested a change, and see that the change was pushed by your teammate.

Click the button to merge those changes onto main!

Switch back to your local main and pull until you have everyone’s changes.

At this point, npm run main should output all the updated greetings!