A big part of collaborating with other developers on a project, whether it be at work or on an open source project, is creating and reviewing Github pull requests. Today I'm sharing five tips for creating effective Github pull request descriptions. These tips will help you ensure your pull request is easy for reviewers to understand and thoroughly review. They will also help your pull request to get reviewed more quickly, by being explicit about what was changed and how to QA it.
Let's dive in to sections worth including in a pull request description.
High-Level Details on What Was Changed
Providing a concise bulleted list of what was changed is a great first step. Linking to a ticket or open Github issue is great, but let's be honest -- who wants to have to put the pieces together on their own? Make it easy for your reviewer by noting the key changes included in your pull request.
If you are implementing something that was scoped out in an engineering proposal, link to that document. Also, if you are implementing a UI feature, link to the designs.
Open Questions
You may have some lingering questions relating to the changes that you had to make. Why not call those out in your pull request description, if you didn't already have a discussion about them beforehand? In addition, if you're looking for feedback on specific changes that you made, call those out as well so that your reviewer can provide input.
How to Test
This is an important one that is often missed. Make it easy for your reviewer by providing explicit steps on how to test your changes. It's often nice to use a checklist format, which is easy to do with markdown, so that your reviewer can even go through the list and check off completed steps. For example:
- [] Start dev server at http://localhost:3000/about-us
- [] Confirm that the navigation menu's open/close feature now works on mobile
- [] Confirm that the navigation menu still works the same on tablet and desktop widths
- [] Check that tests added are complete
If your pull request includes the addition of a new library, note that in the steps so that your reviewer knows to install it first.
Screenshots
For UI changes, include one or more screenshots of the completed feature. If you fixed a bug, it's nice to include a "before" and "after" screenshot so that your reviewer can see exactly what you fixed.
Notes
If you have any other notes to add for your reviewer, such as specific aspects of the work that are out of scope or things to address later, this is the section to note them.
That's all! One final tip: once you're landed on the appropriate format for your teams' pull request descriptions, you can create a pull request template for your Github repository, so that all pull requests will get those sections included by default.
If you have more ideas for effective Github pull request descriptions, please share in the comments :).
Image by Glenn Carstens-Peters via Unsplash
Top comments (0)