Professional Pull Requests
I remember going camping when I was a kid. My father was crazy about his checklist. The day before we’d go through and check it all off as we packed. Sometimes we changed quantities or added or removed items based on our previous experiences.
Popmenu Engineering knows this is the right way to do pull requests. Well there are a couple other things, but we really love the checklist.
Clear Title
When you can, use verb-first titles which describe how introducing the PR will meaningfully change the software. Keep it short and informational so you or others can refer back to it in the future.
Concise Description
Our goal here is to serve our audience, those reviewing your code for merge, or those coming back to understand why a change was made. Make it as easy as you can for them, because it might be future you.
Bullet points are always easier than a paragraph, and following the verb-first format of your PR title is more than adequate. Focus on the product or technology changes, depending on the scope and purpose of your change.
Screenshots
Again, we want to make reading our PR a simple and pleasant task. Screenshots and videos are critical. You can produce them as you do your final smoke test, that way others won’t have to run your code to see the changes. The images can even be used for knowledge base and support documentation. At Popmenu we add tons of screenshots to our PRs.
The Checklist
This is the important part. There’s no silver bullet here, no ‘perfect checklist’ that will prevent all production issues and all efficiency or style mistakes. But you can learn as you go.
Each checklist item is described in detail in our application’s docs repo. Things change, and any engineer can propose changes to the checklist with a pull request.
Our checklist ensures:
- Adequate unit and feature testing of front and back-end applications
- Thoughtful and careful database and configuration changes
- Incomplete functionality is not exposed to end users
- Application functions are protected appropriately by auth/auth
- Changes are backwards compatible and do not disrupt other teams
Be Intentional
Really, all you have to do is decide to treat your PRs as your last chance to make sure you’ve arranged your thoughts correctly and that you won’t embarrass yourself with a production issue. If you’re an engineer just starting out, make your own checklist if you have to. If you run a department or squad, add a Pull Request Template on Github.
Don’t be like me. The first time I went camping on my own, I didn’t make a checklist. I brought 1 full and 1 half-full bottle of water in total and only had sneakers with no tread on the sole.
