When developing changes, it’s imperative to have a way to trace your steps. After building out a change, it’s crucial to create and submit a pull request. A pull request (PR) is a proposed change to a codebase. Essentially, a pull request explains what your code changes will do when added to the repository. It gives your team a chance to review and understand your proposed changes before accepting or pulling in your code, which is where the name “pull request” originated.
Why You Need a Pull Request Template
Developers on your team may not know why they should be adding documentation to their pull requests. When submitting a pull request, your teammate may think, “Here’s my code. You should be able to figure out the rest, right?” Not always — the code reviewer does not have the same context as the developer. Creating a PR template makes it easy to clarify what the proposed changes will do and receive actionable feedback from your team.
Having a custom template facilitates clear communication between all team members and ensures that everyone is on the same page. Moreover, by establishing the culture and expectations (and the why) of pull request templates, developers will be more likely to use them! Ultimately, they set a standard for documenting changes to your project, streamlining the coding process.
Templates can be customized to fit your team’s needs, but here are some things to consider including in your pull request template:
Essential Components of the Pull Request Template
Ask yourself the following questions when writing a short summary for your pull request: Why is this change happening? What feature does this implement? What issue or bug does this fix? What context or history do I need to understand this change? What can I do to ease the mental load for the reviewer? Including a link to the issue on Jira/Trello/etc also makes sense here.
Steps to Test
When looking over your steps to test, the code reviewer will likely wonder: How do I confirm that you actually added the feature or fixed the bug? Is there a specific page or flow I need to go through in the app to see the change? Do I need to add new environment variables, run new migrations, or do anything else? Including the answers to these questions in your PR is especially helpful for providing feedback and verifying your change!
Caveats or Concerns
Here you can add any other details you’d like to bring to the attention of the reviewers. Did you try other solutions first that didn’t work out? Does your implementation have any potential performance or accessibility issues? Does this change introduce a breaking/non-backward compatible change?
Overall, these three components are the most impactful, but here are some optional sections you can add to your pull request template:
Optional Content to Include in Your Template
- Checklists — These can be as short or long, as specific or general as you want.
- Steps Before Submitting
- Did you write tests?
- Did you write/generate documentation?
- Did you lint/format your code?
- Deployment Considerations
- Does this require new schema migrations to be run?
- Does this require new data to be available inside a database?
- Does this require a new build step to be run?
- Does this require new environment variables to be set?
- Is this behind a feature flag that needs to be toggled?
- Steps Before Submitting
- Screenshots / GIFs — For visual changes, including an image with your change can help reviewers know what they should be looking for. After all, a picture’s worth a thousand words 🧐.
- Device and Browser Compatibility — Does this work in <browser(s) you need to support> on <device(s) you need to support>?
- Accessibility — Are there any accessibility concerns or issues?
- Internationalization — Does your pull request require translations?
When creating a PR template, choose what makes the most sense for your team and provides the most value. You can always change it later! For inspiration, check out this example of a pull request template below:
If you haven’t created a custom PR template before, GitHub has a helpful document about how to do so. A custom template fosters a sense of community when working together on a challenging project — add emojis to make completing a pull request more fun! Ultimately, pull request templates simplify the documentation process, setting your team up for success and providing a way for everyone to take pride and ownership in their work.