I have been maintaining open source code for the past three years.
These are my tips for making better pull requests.
This is a short article, but you can check out this Twitter thread for a faster read.
Tip 1: Follow Contributor Docs
Most open source projects have contributing docs (usually a CONTRIBUTING.md file at the root of the repo) that cover how to set up your development environment, coding conventions, areas to contribute to, and more.
If you are looking to contribute to a project, it should be the second place you look into after the README file.
Tip 2: Make Small and Focused Pull Requests
For the most part, your pull requests should do one thing and one thing only.
The problem with addressing multiple things in a single pull request is that the reviewers may only approve some of the changes, which could lead to lengthy discussions.
Small and focused pull requests reduce the time taken for reviews and make them likely to be merged.
Tip 3: Add Tests
If you are adding new code, make sure you also add automated tests.
A general rule of thumb is “If it can be tested, it should be tested.”
Tip 4: Use Pull Request Templates
Most open source projects have templates to guide contributors to document their pull requests.
The template shown below has sections for the contributors to fill in:
Tip 5: Make Sure the Automated Tests Pass
Projects often run automated tests on all pull requests.
These tests are in place to ensure the code you add doesn’t break any rule or code. Most projects have linters, build checks, and unit and integration tests.
If these checks are not passing, fix them and make sure all the tests pass before requesting a review.
Your code is unlikely to be merged if any of these checks are failing.
Tip 6: Document Your Pull Requests
This is probably the most important tip.
The goal of documenting your pull requests is to make the review process as easy as possible. A reviewer should get the context of your pull requests by skimming through their descriptions.
For this, you can:
Write self-documenting code
Use comments liberally in your code
Write clear commit messages
And most importantly, write what your pull request does clearly
In the example below, the description shows what issue the pull request fixes, the changes made, and the change to the user experience.
This makes the pull request very easy to review.
Tip 7: Respond to Feedback
When you open a pull request, you are also opening a discussion on why the change is needed and why your pull request is the right way to add that change.
Make sure you respond to reviews, make changes as suggested, and ask for clarification if needed.
This would make the review process easier by getting you and the reviewer on the same page.
Tip 8: Be Patient
Some open source maintainers are volunteers and spend their free time on the projects.
They may take some time to get to your pull request and review it.
Be patient while they do their thing. Take a break, drink a glass of water, and watch reruns of The Office.
I write a lot about my experience in building, scaling, and maintaining open source projects.
So make sure you subscribe below for more such tips.
Thank you for reading "Pull Requests like a Pro."