I’ve found that the more informative I make my pull request descriptions, the more quickly they get reviewed and the less bugs they generate in the future. To this end and to avoid annoying my colleagues, I follow a few guidelines on how to write a good pull request.
Provide Context
What is the nature of these changes? Are they a bug fix? A new feature? Something else? The person reviewing the changes may be starting with no knowledge of the context around your work. If you’re working with a git system like GitHub or BitBucket and there’s an issue associated to your work, link to it in the PR description. Similarly, if you’re using a ticketing system like Jira, you can link to the ticket in your PR description.
If the issue or ticket doesn’t fully clarify the context of your work, add more info.
Testing Instructions
Most of the time your changes will introduce a functional and/or visual change. How can your changes be tested? Is there specific acceptance criteria to be fulfilled? Provide your reviewers with all the information they need to test your work.
Before/After
If your changes introduce visual or behavioral changes, tell the reviewer where to look for these and what to expect. This is a good time to provide comparative details like screenshots of the visual differences.
Step By Step
Reviewers may not know how to see your changes in action if they’re not already familiar with the product or interface being affected. If testing your work requires more than a couple of steps it can be helpful to spell those steps out explicitly.
Example Pull Request
The code snippet below is a Markdown format template that can be used as a starting point for writing a comprehensive pull request description. This markdown can also be found on GitHub.
## Description
This is where the general description of the changes goes. If there is a bug being fixed or a feature being added, describe it here.
Relates to https://examplesite.atlassian.net/browse/{JIRA-ticket-number} (The related Jira ticket link, if one exists)
Resolves #123 (the GitHub issue being resolved, if one exists)
## To Test
This is where to describe any testing steps that might be required to confirm the visual or functional changes.
1. Do this thing.
2. Then do this.
3. Finally do this.
### Before
This is the visual or behavior you should see before these code changes.
Share screenshots or other visual aids here as appropriate.
### After
This is what you should see with the new changes in place.
Share screenshots or other visual aids here as appropriate.
## Additional Notes
Is there anything else that your reviewers should know when testing? Special exclusions or edge cases?
