Create a Good Pull Request — with Examples and Templates
As business grows, teams become bigger, the codebase also grows and it becomes necessary to keep track of changes through code reviews. This practice helps ensuring that the software remains defect-free, well documented and complies with common coding standards. Moreover code reviews facilitate knowledge sharing amongst developers which accelerates new team members integration.
We cannot talk about reviewing without talking about pull requests. A pull request let you tell others about the changes you‘ve made to a branch in order to discuss and review with them before merging your changes to the main branch.
Bad Pull Requests are expensive !
Time is money! And code reviews take too much time due to bad pull requests. They can take almost the time spent to write the code, and this slows down the work . The reasons are multiple, for instance:
- The pull request is not explicit about what it does: a PR with no meaningful title or branch name, without a description and with random commits is considered a headache for the reviewer. He will spend too much time trying to understand what it is about before starting his review.
- The developer forgot about some obvious things: he didn’t fix tests, the UI is not conform to the design and so on. The reviewer in this case wastes time writing those obvious reminders that could have been avoided if the developer had a checklist of the necessary things he should check before asking for a review.
What is a Good Pull Request?
A good pull request makes code review easier to anyone in the company who could be reading it now or later. No assumptions should be made, like already being familiar with the context or being part of the project for so long. It also relies on rules made by the whole team so that everyone follows the same pattern and everyone understands it.
Basically, a pull request consists of 3 things:
- Title.
- Description.
- Commits.
A well written pull request is a combination of meaningful names, straight forward description and well done commits.
How to create a Good Pull Request in 3 Steps:
Making a good pull request starts in your local environment when you commit your work. So the first step is to make good commits.
Step 1: Make Good Commits
A good commit is a reference where you can go back and run the project with no problems. It functions like a working snapshot at a certain point of time. So make sure that the project is working whenever you do a commit.
A good commit does one thing. Try to make multiple commits that represents multiple independent changes. For example, let’s say you’re developing a page that displays a list of articles that comes from an API. Creating multiples commits can look like:
- Create articles page component
- Create service to get articles from API
- Create article card component with style
- Add components and service tests
This way, the reviewer has already the headlines of what you’ve done just by looking at the commits messages. Moreover, it guides him to follow the logic you have followed to build and understand you better. And it’s definitely better than having one comment like:
- Create articles page
It doesn’t tell you whether it’s an empty page, a page with static data or a page with real data, and it doesn’t tell whether you tested your code or not. Every information needs reading the changes.
If you are afraid of creating too much commits for each feature, and don’t want to be drawn in commits that has no purpose in your main branch, you can use squash and merge instead of merge. Your pull request’s commits will be squashed into a single commit (that you can specify in the pull request), and they just serve at the code review stage.
Read more about squash and merge:
- GitHub docs:
- GitLab docs:
- Azure DevOps docs:
Step 2: Give a meaningful title to your Pull Request
The title of the pull request should explain the purpose of the changes at a high level. It shows the general context and tells why the changes should be made to the project.
Here is a suggestion of Pull Request naming convention:
- Short and informative: serves as a summary
- Prefixed with corresponding ticket/story id (e.g. from Jira, Trello, GitHub issue, etc.)
- Prefixed also with [Frontend], [Backend], [DevOps], etc.
- Written in imperative present tense
Example: #777 [Frontend] add articles page
This title above, even before clicking the pull request to see details, clearly tells you that this pull request consists of adding a new page for displaying articles in the frontend and gives you the ID of the corresponding user story or ticket to check it out.
Step 3: Describe what you’ve done
Documenting pull requests is important, similarly to how documenting your code is. It’s a reference to the history and understanding of the changes made to the application. Moreover, if it’s done well, it gives code reviewers and testers more confidence in really knowing what’s going on.
Your pull request description should be the answer to those questions:
- What is the feature?
- How you implemented the solution?
- Does it impact any other area of the project?
- Any changes in the UI (Screenshots)?
- How to test the feature (A test scenario or any new setup)?
If it’s frontend, it is very helpful to attach screenshots of the feature, screenshots of the mock-ups, or screens before and after fixing bugs, which allows reviewers to validate the work without having to pull the branch and do a bunch of unnecessary work that takes time.
It can be useful also to tell the testers or reviewers how to deal with the feature, how to test it or if there is some new environment setup that should be done to test the feature.
Help your team write good Pull Requests
To help your team write good pull requests, make sure you are all aligned on what a good pull request should look like. This could be achieved by adopting naming conventions that are clearly written on an onboarding documentation, and by suggesting pull requests templates to help them write useful descriptions.
Advantages of using Pull Requests templates:
It saves time, and here is why:
- Makes developers check their code themselves and make sure they don’t have any dump error that they should fix before asking for code review (errors in console, work doesn’t meet the acceptance criteria, any other accurate error related to the technology …).
- Standardizes the form of pull request’s description so that everyone, junior as well as experienced developers, can write a good description. So, everyone follows the same pattern and everyone understands it.
How to add a Pull/Merge request template to your project
How to add MR template to GitLab project:
How to add PR template to GitHub project:
Hw to add PR template to Azure DevOps project:
Examples of templates:
Bug fix template example:
## Summary(How to reproduce the bug?)
(What was the reason?)
(What is the solution?)## Checklist- [ ] I fixed|updated|added unit tests and integration tests for each feature (if applicable).
- [ ] No error nor warning in the console.
- [ ] I joined a screenshot of the app before and after the fix.[upload the screenshot here]
Adding new feature template example:
## Summary(Summarize the changes that have been made to the platform)## Checklist- [ ] I fixed|updated|added unit tests and integration tests for each feature (if applicable).
- [ ] No error nor warning in the console.
- [ ] I joined a screenshot of developed feature (if applicable).[upload the screenshot here]
A simple template example:
## Summary(Summarize the changes that have been made to the platform)
(Include screenshots if any)
Another template example:
### What is the feature?
(Describe what the feature is)### What is the solution?
(Describe at a high level how the feature was implemented)### What areas of the site does it impact?
(Describe what parts of the site are impacted and*if*code touched other areas)### How to test?
(Describe the prerequisites and the steps to test)## Other Notes
(Add any additional information that would be useful to the developer or QA tester)
Bonus:
- All the previous recommendations are opinionated and no rule is a strict necessity. So feel free to create your own rules to make your pull requests better.
- If the code written is not good, no rule is going to help minimize code reviewing time 🙂.
- Once you start ignoring the templates you’ve created, either update or delete them, they’re not supposed to be there as decoration.
