Photo by Sebastian Coman Photography on Unsplash
Preparing a Gourmet Pull Request
This idea has been marinating in my head for over a year, and I'd been stewing over how to present this topic without it being bland. (I almost wrote "breadfully bland", but I thought batter of it.)
If you like mixed metaphors as much as mixed greens—and as little as you like mixed indentation—pull up a chair and feast your eyes on my method for preparing a gourmet pull request.
Health benefits of this preparation method include:
- Improved digestion: faster reviews
- Increased serotonin: happier reviewers
- Reduced cramping: fewer merge conflicts
- Less wiping (sorry): cleaner git histories
Ingredients
Let that issue ripen on the issue tracker vine until it's ready to be plucked.
Fresh
A gourmet pull request starts with the freshest ingredients. If your branch is small, fork it from the branch where it will be merged (the "main branch"). If the main branch changes before your pull request is merged, rebase off of that branch instead of stuffing the new commits into your branch.
The hamster is your branch and the carrots are new commits to main.
If the main branch were a main course, its new commits dessert, and your commits a digestif, surely you would have them appear in that order in your commit history rather than main, digestif, dessert. Quelle horreur!
To make rebasing as smooth as possible, sift unnecessary commits out of your branch by squashing it into as few logical commits as possible — with good commit messages, of course. For example, if you branch involves refactoring code to make it easier to add a new feature, consider using one branch for the refactor and one branch for the feature. This helps code reviewers see which files have new code and which have refactored code.
Plus, the fewer commits you have, the fewer times you'll have to address possible merge conflicts.
Ripe
Your pull request must address an issue that is ripe for the picking. If you start an issue which which the project isn't prepared, your branch may spoil before it's merged: the code in your branch could fall so far behind the main branch that merge conflicts make it prohibitively difficult to rebase, or the branch may be deprecated because of product-level decisions.
Let that issue ripen on the issue tracker vine until it's ready to be plucked.
Local & Organic
There's a time and a place for cinnamon, but does your galette aux pommes really need it if it already has nutmeg? Avoid unnecessary additives in your branch, even if they're well-intentioned. These additives can take many forms:
- Unrelated changes: if you notice incorrect formatting in a file your branch doesn't add or remove code from, or a potential refactoring opportunity that is out-of-scope or in-scope just a little bit, it's often better to create a new task to keep your branch trimmed and lean.
- Dependencies: avoid adding unnecessary dependencies. If your project already uses date-fns for datetime formatting/manipulation, for example, don't add Moment.js.
- Duplicate implementations: check that your branch doesn't add code that already exists in the project, like a utility function or a TypeScript interface.
Method
If the proof of the pudding is in the eating, the proof of a pull request is in the seeing.
A gourmet pull request is greater than the sum of its parts, more than mere lines of code—after all, it isn't code crudités. Would you serve a soup unsampled? a gratin Dauphinois ungarnished? Certainly not.
Along with what your pull request contains, how you present your pull request is also important.
Prepped
Do a pre-review on your branch before you open a PR by comparing the diff of your branch and the target branch. This makes it easier to notice small issues in your pull request and gives you an opportunity to correct them before they're visible to reviewers. People will think you're an even better coder than you are. Hide your shame!
Online version control software like GitHub, GitLab, and Bitbucket supports this, and it's a convenient way to do a review of your own code using the same interface other users will use to review it.
Raw diffs have an unpleasant mouthfeel and can be difficult to digest. To review your changes outside of GUI version control software, you can use an alternate console-based diff interface like delta for a smoother, more palatable git diff experience.
Plated
Presentation matters. A put-together pull request provides a powerful pfirst pimpression. (In my writing, alliteration and shamelessness are positively correlated.)
Pull request descriptions can provide helpful information that makes a reviewer's job easier. If your branch's code includes something surprising, or if there was an obvious implementation that was incompatible with the project for some reason, be sure to include that information in the description.
The more questions you can preempt in your pull request description, the smoother the review process will be. If a pull request includes style, layout, or workflow changes, for example, include a photo or animation showing those changes. If the proof of the pudding is in the eating, the proof of a pull request is in the seeing. If the code checks out, that review will be downright creamy.
Served
Like a dish, your pull request needs to make it in front of the right person. Can you imagine a delicious dish deserted? delivered to the wrong table? Assign your pull request to a reviewer so it doesn't get cold.
If your project were an upscale counter-served restaurant, it is your duty to ensure that your customer (the reviewer) receives the order (the pull request) to consume (to review). It isn't enough to call out a number one time. If you assign a reviewer to a pull request, and that person doesn't pick up what you put down, you must find that person.
Assigning reviewers to your pull request.
Pull requests, like cornbread, can get stale and hard if they sit for too long. Being proactive with soliciting reviews will keep your code-cornbread soft and warm.
Gourmet take-away
If this article were a gourmet meal, this conclusion would be the dessert. Like a flourless chocolate torte, I'll keep this short and sweet.
A pull request isn't just code, much like a meal isn't just ingredients. Your pull request provides tasting notes to your reviewers, letting them know what to expect in and how to appreciate your gourmet pull request.