Pull Requests for Teams

Sunflowers, 1887
Vincent van Gogh

If you recognize a measure of truth in the proverb:

Two heads are better than one,

you will want to experiment with the Pull Request workflow with your next software team.

Pull Request Workflow

The Pull Request workflow, implemented by popular shared source code repositories like GitHub and Bitbucket, is an excellent means to spark team discussions and improve code quality.

Like a classic Greek ode, the Pull Request Workflow has three call & response parts:

1. Branch;
2. Discussion; and
3. Merge

Pull Request Workflow: 1. Branch; 2. Discussion; and 3. Merge

Following is a sample workflow for a hypothetical feature called more_cowbell.

1. Branch

Assuming you have already cloned (downloaded) a shared repository to your local machine, the first step is to create a branch off of the trunk (often called master).

Following are series of git terminal commands that will get you to the point where you can modify code. Typically you will create a local branch from the shared repository to work on a new feature or a bug.

Create the more_cowbell branch as follows:

(master) $ git checkout -b more_cowbell

Then checkout the newly created local branch as follows:

$ git checkout more_cowbell

Think of more_cowbell as your local sandbox. Now make additions, deletions, or changes, then create/run unit tests and integration tests, and commit your changes. Or if you prefer test-first, do the tests first, then commit.

(more_cowbell) $ git commit -am "Add more cowbell"

Finally you're ready to push your changes back to the shared repository for review, discussion, and a potential merge back to master.

(more_cowbell) $ git push -u origin more_cowbell

2. Discussion

Go to your shared repository on GitHub, Bitbucket, or other. Locate the more_cowbell branch you pushed in Step #1.

GitHub and Bitbucket both have side-by-side comparison tools. Use the compare tools to carefully inspect the proposed changes by comparing more_cowbell with master.

When you're ready to open your proposed more_cowbell changes to a team discussion, locate and click the Pull Request link (or button).

Your teammates will be notified of your Pull Request. They will then review your changes, post comments on individual lines of code, or post general comments on the Pull Request. Typical comments might involve issues with formatting, the location of a method, notification of code duplication, suggestions for refactoring, etc.

It is courteous to respond to the comments posted on your Pull Request in a timely and respectful fashion. A concise and courteous response from you following a "you might want to..." comment might be:

"Good catch. Will do."

Some teams use round-robin to determine who reviews a given Pull Request with each developer assuming the role of reviewer. Other teams assign one or more lead developers to review all the Pull Requests. Most teams encourage the entire team to look at and comment on Pull Requests as time permits.

Others may add commits to your branch by doing a fetch and a checkout of more_cowbell on their local machines. They would follow the same workflow of modify, commit, and push back to the shared repository. Presumably more discussion would ensue.

3. Merge

After ample discussion, and perhaps following some additional changes or tweaks that have been suggested to you, someone other than you will merge your changes to master.

Summary

For me, the essence of a Pull Request is:

• to learn from my teammates, and
• to agree upon what constitutes a worthy addition or an incremental improvement.

Like me, most developers readily agree that code reviews improve quality. And like me, most developers dread the traditional code review because it often means an uncomfortable one-on-one encounter with a high-ranking alpha developer where one is made to feel defensive or worse, incompetent.

Pull Requests feel less authoritarian and more democratic. It is a lightweight quality improvment process more in the mode of discussion and edification, than in the mode of admonishment. It has been my experience that Pull Requests spark discussions about the code and the craft which, in turn, tends to improve the quality of the code.

I'm all in favor of the democratic principle that one idiot is as good as one genius, but I draw the line when someone takes the next step and concludes that two idiots are better than one genius.
-Leo Szilard

References

• Work with Pull Requests, Bitbucket.org.
• Using Pull Requests, Github.
• Effective pull requests and other good practices for teams using github, David Winterbottom, October 20, 2012.