A great Pull Request (PR) should read like a high-quality blog post.
I'm sure everyone's experienced this, you open a teammate’s PR only to find a blank description, an obscure title, and a wall of changed code.
You have a million questions. What is this? What issue does it fix? How do I test this? Who approved this decision? Who did you speak to? What were the trade-offs? How do I run this locally? What visually does it change? Why did you do it like this?
Sloppy PRs are a plague on development teams, laziness leads to bad habits, random project nicknames, and a sea of unexplained acronyms that nobody else understands. When you submit a lazy PR, you are telling your team, "my time is more valuable than yours."
For those early in their career, mastering this skill is one of the fastest ways to stand out and show great professionalism. To demonstrate clear technical communication.
It's one of the telling signs of a poor development culture. It can snowball, once this becomes culture, normalised, developers can get more and more sloppy.
A PR requires the reviewer to checkout the code, review it locally and verify it works. This can take days. It doesn't mean put your finger in the air and glance at the code to get sense if it's OK. However if your pull request looks like this that's can encourage that behaviour. Throwing it over the fence getting someone else to do the work.
The 1 year test
When you open a PR, imagine you are returning to this exact page in one year's time. The context will be completely gone from your memory.
A great PR acts as a permanent historical record for your repository. It bridges the gap between your immediate thoughts and the long-term documentation of your codebase.
Anatomy of a high quality PR
To write a PR that your teammates will love to review it can follow a simple format.
What
Link directly to the tracking ticket or issue. State exactly what problem this code solves.
Why
The "Why" document the technical trade offs you made and mention who you spoke with to align on this solution.
Screenshots
If you changed the user interface, attach a screenshot, an image, or a short video demonstration.
Anything else?
Write a step-by-step guide explaining how the reviewer can pull down your branch and verify the changes locally.
Ban internal acronyms
Add comments to the code. If someone is unclear of there is something that needs to be explained add this.
Add any resources that support your decision, how did you arrive this?
Create a markdown template
The easiest way to break bad PR habits is to automate the process. You can use platforms like The GitHub Blog to set up a standard pull_request_template.md file in your repository.
When a template autofills every time a team member opens a new branch, it forces everyone to slow down, fill in the blanks, and provide the clarity the team deserves.
Top comments (0)