Creating Delightful Pull Requests
How To Make Reviewing Your Code a Breeze
As I’ve said before, there is always a story behind a blog article, and it’s incredible to note that most of mine start with reviewing a Pull Request (PR for short). I take it as a creativity-boosting activity.
But despite my liking and dedication to the PR reviewing process, I have found myself frustrated and procrastinating about reviewing some PRs. It hurts to say it, but this article was born out of that sentiment of frustration.
Please don’t get me wrong. I’ve seen many delightful PRs, and I’m grateful for that. But happiness wouldn’t make for a good story. Let’s focus on what needs fixing or improving.
The main reason I’m writing this article is my wish to improve the quality of our PRs, and thus the reviewing process, by promoting some good practices. That is why I’m scoping it down to the first step of the process: crafting.
When in Rome
Once upon a time, I was walking in the streets of Rome when… Not really. This story is not about a trip to Rome but the idiom: “When in Rome, do as the Romans do.”
As developers, we learn from other developers. One popular technique to onboard new developers to the team is to “shadow” a fellow developer. This technique is not for learning code-specific skills but for picking up tricks and tips on the development culture and the team’s know-how, including how to present your work for peer reviews. I know I read quite a few PRs in my team’s repo before I crafted my very first one.
Therefore the best way to improve and leverage the delightful PRs culture in the team and the company is to lead by example. Take the time and make an effort from the beginning. Crafting a delightful PR starts before the first line of code is written. It starts by breaking down and organizing the work to be done.
Craft Tip on Size: “Size matters!”
You want the reviewers to proofread your code correctly. The reviewer does NOT want to spend hours and hours on end reviewing hundreds of lines of code change. Keep it as short as possible. Break down your feature into smaller pieces that make sense on their own and can be shipped independently.
Focus on ONLY one SMALL thing.
Benefits of Small PRs
Easy to review | Easy to spot bugs and issues | Faster to fix | Faster to merge | Fewer merge conflicts.
Craft Tip on Commit History: “Pretend it never happened.”
Delightful PRs also have a delightfully curated commit history. To achieve such a history, you’ll need descriptive and atomic commits that tell a story.
Descriptive: Make sure to add a descriptive commit message, where the summary describes the changes and the body gives the proper context for those changes. For example: “Fix bug” or “Address a PR comment” will not do here.
Atomic: Commits should do only one thing at a time. For example, when addressing PR comments, make sure to split them into separate descriptive commits instead of having one commit. Again: “Fixing some issues” or “Addressing PR comments” won’t do.
Commits that are put together like building blocks, successively building on top of the previous one by logically advancing the feature, are destined to tell a story.
Commits should tell a story.
When you’re developing, your commits might resemble a giant spaghetti ball mess. You’ll want to straighten that out before you put up your PR, so your commits are easily reviewable one at a time.
Pretend it never happened
Keep things clear and concise. You don’t want any filler when you tell the story through your commits. You don’t want any fluff. You want the SparkNotes version.
That means you can remove any missteps. Your reviewers don’t need to know you fixed a typo or renamed variables in a module you added. That can be a secret between you and your local git history.
Similarly, your reviewers don’t need to know if you went in circles and added code you ended up removing. You can pretend that never happened too. You can use git commit history tools like rebase, reset, or squash.
Make them easy to review.
But don’t let any of this overwhelm you. Try to make your commits easy to review. Your reviewers will thank you for it!
Craft Tip on Title: “Use it wisely.”
The title of your PR can do a lot in terms of first impressions.
Some developers like to indicate if the PR is a work in progress by adding a prefix of “[WIP]-{your-pr-title}” as a simple pattern to show this state and instantly let reviewers know it’s not ready yet. Others simply set the PR to Draft until it’s Ready for review. Some others used both. Whichever approach you choose, submit for review only when the PR is ready.
Use it to indicate a multi-part PR. Sometimes a feature is broken down into smaller pieces (advisable), and most of the context is in the PR containing the first piece. By indicating the parts in the title, you instantly let people know what to expect and to check previous PRs.
For example: “{your-pr-title}-[Part I of III].”
Craft Tip on Description: “Context, context, context.”
Your PR description is your chance to shine, to set the reviewer up for an excellent reviewing experience. It is where you will explain what problem you are trying to solve, why, and how.
Your number one task as the writer of a PR is to make sure reviewers get to understand the context as quickly as possible.
As we are all busy trying to ship our work, it’s essential to understand that creating PRs and filling up the description template is not just paperwork. It’s what will take your PR to the top of the reviewing pile or the bottom.
A good description makes reviewing easier. It prepares the reviewer for what they will find in the PR review by pointing them to the areas they should be paying more attention to.
A good description also ensures your final code solution matches the intended solution to the problem.
Descriptions are a great source of documentation. Don’t assume familiarity with the history. Remember that anyone in the company could be reading this Pull Request, so the content and tone may inform people other than those taking part, now or later.
I’ve been trying to stick to the positive DOs as they are more effective for teaching. But this I have to say explicitly.
The following are examples of BAD “what” and “why” explanations in the description.
## What?
See ticket #JIRA-123## What?
See the subject.## What?
Added support for authentication. #JIRA-123.## Why?
Bob, the PM, knows about this.## Why?
Bob asked me to do this.
On Testing Instructions
I see developers often run into a pitfall: they make assumptions about who’s reviewing their code. Don’t do that. If you have a feature involving some third-party tool or platform, write the instructions as if the reviewer has never seen it.
Craft Tip on Formatting: “Make appropriate use of Markdown.”
A delightful description uses Markdown language or anything else the tool supports (if not in GitHub).
Reviewers will appreciate it when the code is formatted as code or code blocks when it's multi-line. Break it into paragraphs. Emphasize the relevant words or phrases. Use emojis, images, screenshots, and animations. Some developers go the extra mile and even like to embed a video where they demoed the feature. A video is sometimes worth 1000+ words. Add custom headers or anything to spice it up and make it more readable.
Add something special for the reviewers to have a good time.👇
Craft Tip on Language: “Language correctness tells on you.”
Please ALWAYS be mindful of the grammar, spelling, and punctuation marks. Some developers might consider these topics nitpicking, but it reflects poorly on the work and gives the impression of a PR written hastily and carelessly.
It doesn’t have to be perfect. We are not English graduates, after all. Some of us aren’t even native English speakers. But make sure you write it carefully and intentionally. And always proofread it yourself before sending it out for review.
Use a tool! We use many tools daily to perform static checks on our code for syntax errors and coding standards violations. Why not do the same for PRs?
Grammarly is an excellent tool if extra help is needed; it is integrated with your browser and provides fantastic and instant feedback and corrections.
Craft Tip on Comments: “To comment or not to comment?”
Commenting on your PRs is a hot topic, and developers have strong opinions.
Do not explain things in PR comments.
Instead, re-write the code, or add a comment to the code base.
But DO explain things in PR comments.
It’s ok to do so when your comment is helpful in the here and now but will not be required or helpful later.
Craft Tip on asking for a review: “Double check your work first.”
Always review your code first before asking for reviews. Not only is it a best practice, but it’s also respectful towards your peers.
Doing things right the first time is cheaper and more efficient.
Craft Tip on Reviewers: “Make their lives easier.”
Putting yourself in the reviewer’s shoes is the best ticket to a successful review process. Always know who is reviewing your PR. The reviewers, in this scenario, are your users. Be User Obsessed and intentionally work to make their lives easier.
At Prodigy Education, we have defined a domain-based set of reviewers. When changes in your PR are touching multiple domains, involving more people in the review and approval process, consider breaking down the work by domain. It will first make your PR smaller, which is always a way to go. Second, you’ll be reducing the number of people (code owners) you need to get approval to merge your PR. And third, you’ll be thinking about the reviewers and sending their way ONLY changes to parts of the code they are familiar with and invested in.
Also, if you want to get some individuals involved in the PR review process, feel free to @mention them, specifying why you invited them to the discussion.
It takes reviewing a lot of PRs to get in tune with the needs of the reviewers. But don’t despair. Even if you don’t have all that practice, these tips ☝️ and plain old common sense will go a long way.
The End
Alas, this is the end. But not really. It is just the first step, a crucial one, but not the only one. After creating your delightful PR, you’ll deal with the rest of the review process.
Be ready and open-minded for the incoming feedback. Hopefully, your fellow reviewers will make use of their Radical Candor skills. Embrace it! Own it! Extreme Ownership is the way to go. Own your code, decisions, and feedback, the good and the bad. And learn from it. Switch to Growth Mindset mode, and develop yourself and those around you. Code reviews are the perfect learning opportunity for all.
Acknowledgments
Thanks to Jonathan Richardson and Lilly Dinh-Le for the informative and practical presentation you put together a while back. It served as a big inspiration for this article.
Additional Resources
- PluralSight course: “Code Review: Best Practices” by Andrejs Doronins.
- Writing a Great Pull Request Description
- How to Write the Perfect Pull Request
- Forcing Function For Great Pull Requests
- The Anatomy of a Perfect Pull Request
- How to Make a Perfect Pull Request
- Non-technical article about writing about happiness
- Prodigy’s Cultural Values:
Radical Candor | Extreme Ownership | Growth Mindset | User Obsessed
