Creating meaningful pull requests
As a software engineer at Red Squirrel, I’ve had many opportunities to work with a variety of different teams all with varying ideas of what it means to create effective and clean code and the processes in which to do so. What has always seemed to “return true” is that good collaboration is key to developing meaningful software. At the base of good collaboration has always seemed to be a good pull request.
What is a pull request (PR)?
In its simplest form, it’s a means of notifying others of new code changes we’ve made and features we’ve created for the project. It’s how we ship our work.
Why is a good pull request important?
The better we represent our code the more likely other will be engaged with our changes, setting up reviewers to provide better and faster discussions. They also serve as documentation for the development process. It helps inform other developers, current and future, about the reasoning behind the implementations and the patterns used by providing insight into the state of things when the PR was made.
So how do we make a good pull request?
Here are some commonalities I’ve found in good pull requests:
1. The title and description matters
By having an explicit title and descriptive summary you set up a reviewer/collaborator with a succinct context that helps them at a glance understand the what, why, how and where of the feature, bug fix, tests, etc. that you’ve created. The most helpful and easiest way I’ve seen to achieve this is by using a template.
Here is a sample template I’ve used:
## Problem
- Link to card with acceptance criteria/specifications
- The description of the problem that the PR solves and where it exists## Solution
- How it was solved
- log of changes (models, migrations, etc)## Testing steps
- setup steps
- testing instructions
- expected outcomes## Screenshots
- layout/view changes
- helpful screen shares of changes## Additional notes
- other related PRs
- merging steps
- callouts to areas of concentrated feedback
- etc
2. Add code comments to non-obvious code
When you’re creating the PR, you have a lot information about the changes. You understand the requirements, limitations or issues with the third-party libraries, interactions with legacy code, etc — you write code with all those in mind. There are times where a “why” comment can clear up why the code was written in a particular way.
3. Review/comment your own PR
When I first saw this done by another engineer, it definitely caught my attention. What I realized is that these comments quickly provided context and drew special attention to areas of concentrated feedback. Now, whenever I get a chance, I make it a point to do the same. At times doing this has also made me realize when PRs have gotten too large.
4. Size matters, keep them small
Smaller PRs get reviewed faster and reviewed better. It’s likely that if you’ve reviewed large PRs you have experienced review fatigue. Holding context of a large PR is very consuming, which could result in a less than ideal review. So, in this case size does matter.
Conclusion
Good Collaboration and communication have always been the foundation for a quality developer experience and an effective team. Creating meaningful pull requests is a great opportunity to reinforce that base. These are just a few tips I have found for making great pull requests.
Happy coding!
