A guide to idiomatic pull requests

Are you still raising blank pull requests with a 2–3 line description? Does it take a long time for your PRs to get merged? Do the reviewers need to sync up with you for understanding your PR’s context?

If the answer to any of these is yes, then you need to level up your PR game and I’ll be showing you how to do so in the below steps -

1. Make PR templates

The fastest way to level up your pull requests is to use a template. I would recommend using individual templates aka one template for bugs and one template for your features.

Feature template -

## Description
Add bullet points or short summary about the change. Also, include the relevant
motivation and context.
## Screenshots
### Before
### Now
## Test cases covered -
[ ] verified theming
[ ] verified responsiveness  
[ ] added unit tests
[ ] -- add relevant test cases to be covered here
## Edge cases covered - 
- edge case 1
- edge case 2
## Endpoints
- URL endpoint
- login credentials
## Checklist -
[ ] Needs design review
[ ] Verified DOD
[ ] -- add relevant checklist items here

Bug template -

## Issue
Add a short summary describing the reported bug
## Root cause
Describe the root cause of the bug
## Fix
Explain the implemented fixed for the issue
## Screenshots
### Before
### Now
## Edge cases covered - 
- edge case 1
- edge case 2
## Endpoints
- URL endpoint
- login credentials
## Checklist -
[ ] Needs design review
[ ] Verified DOD
[ ] -- add relevant checklist items here

To add these templates to your Github repo, just add a .github folder to your repo, add “PULL_REQUEST_TEMPLATE” folder in there, and then save the above templates in “.md” file format.

Doing so will generalize these templates for anyone raising a PR and improve the PR readability.

Now you’ll be able to access these templates by adding query param “template=filename.md” at the end of the PR creation URL.

2. Use screenshots or screen capture

A picture is worth a thousand words.

Don’t overcomplicate your PR with a lot of text, keep it simple and let the screenshots talk more. It’ll be even better if you highlight the portion of the screenshot you want the reviewer to focus on for the before and after images.

If you’re PR updates a workflow then it’ll be better to record the old and the new behaviors. The best tool I’ve found to do so is loom — https://www.loom.com/

It takes effortless screen recordings and saves them for you on the cloud. You can just link the URL in the “before” and “after” sections of your PR template.

With local screen capture, you’ll have to make sure that the file does not exceed the max file size for a PR and then wait for it to get uploaded on Github as well.

3. Smart PR heading

Instead of using PR headings like -

use -

Ticket ID:

Helps reviewers to quickly pull up the ticket and you can additionally add automation to map these MR to show up in your ticketing system like Jira.

Feature or Bug:

Right after the ticket ID, point out if the PR is adding a new feature or fixing a bug.

Description:

Instead of using vague descriptions like “Updated readme.md”, use one line to set up the expectations for the changes and context of the PR.

4. Use correct tags

Four tags you should never leave blank are -

1. Assignee — there should only be one assignee per PR
2. Reviewers — Add other reviewers here who can contribute to the PR review process
3. Labels — Create labels for the different features you have in your project, and some custom labels like “needs design review”, “on hold” etc, and tag the correct labels for each PR
4. Milestone — Create milestones for each release and tag the correct milestone for each PR

5. Be empathetic

Be empathetic towards your PR reviewers. You can use the following key points whenever applicable.

• use buttle points instead of big paragraphs.
• Don’t copy-paste the ticket info if it doesn’t provide full context.
• Read your PR request in preview mode at least once before creating it and try to read it from the point of view of a reviewer.
• Ask yourself these questions — Am I providing the full context of this PR to the reviewer? Am I being too verbose with my description? Have I pointed out the potential edge cases?
• Also, keep an eye out for good PRs habits and incorporate those changes in your future PRs.

Benefits of doing this -

I know this is a lot to do for raising a PR but the benefits outweigh the cost. A meticulously templated PR wouldn’t need any ad-hoc meetings for transferring PR context. Reviews will come in faster reducing the merge time.

And reviewers armed with more info are better at finding edge cases and potential bugs which will prevent more bugs from creeping into your codebase.

Do you use any other PR-raising techniques to speed up the review process? Let me know in the comments.

About the author -

Srijan Gulati

Senior Software Developer

Nvidia