Crafting the perfect Pull Request

Defined scope is among the most important features of a good Pull Request. This free little extension will slice your branch until it reaches perfection

I had a dream. And in my dream I type: git log and actually able to follow the log of my git. I can track each change made by any team member, in an incremental and descriptive form, without the need of approaching personally to anyone and asking: “so what’d you do yesterday?”

Cherry pie logo (credit: Shir Keret)

A matter of scope

Writing a good git commit message is an art often discussed, but it is only part of the problem. The bigger problem in our team was restricting each commit to a single atomic change.

Here is an excerpt from the Linux kernel documentation:

Separate each logical change into a separate patch.

For example, if your changes include both bug fixes and performance enhancements for a single driver, separate those changes into two or more patches. If your changes include an API update, and a new driver which uses that new API, separate those into two patches.

On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a single patch.

The point to remember is that each patch should make an easily understood change that can be verified by reviewers. Each patch should be justifiable on its own merits.

If one patch depends on another patch in order for a change to be complete, that is OK. Simply note “this patch depends on patch X” in your patch description.

Following those rules is crucial in a project of any size since they provide us with:

1. Descriptive log of the changes made to the code over time, without any “hidden” surprises.
2. Easy reasoning over any change due to a limited and defined scope.
3. Faster code reviews.
4. Quick revert in case of a problem.

The intentions are good, everyone shares the importance, but delivery is hard.

If you can’t Pick then Slice

So why not “just do it?”

You probably know how it goes — you open a feature branch and the way you see other changes needed to be made. Sure, you should open a new branch, make some work and then go back to your original branch, but this is time-consuming.

In a different case — during a review, you notice some changes that might have better been added as an independent PR. Again there are ways of extracting those changes using the command line, but this also takes time and often skipped.

I believe that if a workflow is not intuitive, then it is broken. A developer will always strive to do the best work, and she should be provided with the correct tools to reduce friction.

After seeing that we are unable to follow the “one change — one commit” rule, I created this chrome extension to make the process intuitive.

This extension allows a developer to extract files from one branch and add them to a new one, with a click of a button within the Github interface

A “Slice” button is added to files in the Pull Request to extract them into a new branch

Why not just cherry-pick?

cherry-pick is a perfect git command which, in a perfect world, allows a perfect programmer to carefully pick her commits and stage them into a new branch, where they can be pulled into master in perfectly organized pieces.

But we are not perfect, we are developers

Though our code is clean, our feature branch’s commits are “WIP” or “fix” or “here’s another try” and essentially — just a whole big mess waiting to be squashed.

Cherry Pie lets you work your way backward: Pick any number of files from a branch (instead of commits) and move them into a whole new branch.

That way you can split a long pull request into numerous atomic and clean ones, with descriptive titles. Bugs will be easier to spot, reverts become a breeze and the guy over there doing your CR would be so thankful he’ll bake you a pie. A real one for sure.

You use cherry-pick for commits, but when commit history is squashed, it turns into a cherry pie. So - if you pick a cherry, you need to slice a cherry pie.

Was it worth it — the results

The adoption was quick. All team members installed the extension and started slicing everything at hand.

1. We have much more PRs but they are very small and easy to review.
2. We can track our changes to the master branch and revert problematic commits without worrying that we are removing important changes.
3. We have complete transparency to the work made by developers and can track the progress of tasks.

Download

You can install the extension from the Chrom Store:

Cherry Pie

…or clone the repository and build your own:

shlomokraus/cherrypie