This content originally appeared on DEV Community and was authored by Navendu Pottekkat
With Hacktoberfest around the corner, here are some tips to make better Pull Requests for your next Open-Source contribution.
As a maintainer and a contributor to Open-Source projects these are the things I look for when reviewing and take care of when submitting Pull Requests.
This is a fast read but if you want one even faster, check out this Twitter thread.
Tip 1: Contributing Docs are your Best Friends
Most Open-Source projects have a contributing doc(usually a CONTRIBUTING.md file at the root of the repo) that contains all the necessary details on how to set up your development environment, coding conventions you have to follow and much more.
If you are looking to contribute to a project, that should be the next place to look into after the ReadME file.
Contributing doc from the Meshery project
Tip 2: Document Your PRs
This is really important. I repeat this is really important.
You should make the reviewing process as easy as possible and a reviewer should be able to get the context of your PR with a quick glance.
For this, you can:
- Write self-documenting code (What is self-documenting code and how can it help? See this great answer)
- Use comments liberally in your code
- Write clear commit messages and
- Most importantly, comment what your PR does clearly
As shown below, the PR description shows what issue it fixes, the change made in the PR and the actual new User-Experience.
This makes the PR very easy to review.
A Pull Request description example
Tip 3: Use Pull Request Templates
Most Open-Source projects will have a Pull Request template to guide newcomers and veterans alike into documenting their PRs properly.
As you can see below, the PR template has sections where the contributors are expected to fill details.
Pull Request template from the Open Service Mesh project
This would make the job of the reviewer much easier as they would be able to easily test it out, ask a domain expert to review and much more.
These also acts like a checklist that the contributor can tick off. For example: Questions like "Did I write unit tests?", "Did I sign all of my commits?", "Is this a breaking change?" can be answered as you start filling the template.
Tip 4: Make your PRs Small and Focused
Whenever possible, your Pull Requests should do one thing and one thing only.
The problem with addressing multiple concerns in a single PR is that the reviewer may not agree with all the changes and this could potentially lead to long discussions.
So small and focused PRs would reduce the time taken for reviews and would make your PR most likely to get merged.
An Example Pull Request with just a single, focused change
Tip 5: Add Tests
If the project you are working on has automated tests, then make sure that you add tests for the code you are adding.
Not sure if you should write tests? Here is a bonus tip:
If it can be tested, it should be tested.
Tip 6: Make sure the Automated Tests Pass
Most projects have automated tests in their CI/CD pipelines which run on your Pull Requests.
These tests are in place to make sure that the code you are adding passes some constraints. These are mostly lint checks, build checks, unit tests and integration tests.
If these checks are not passing, fix it and make sure all the tests pass before asking for a review.
Your code is not likely to get merged if these checks fail.
All checks passed!
Tip 7: Respond to Feedback
When you open a Pull Request, you are also opening a discussion on why this change is needed and why your PR is the right way to add that change.
So, make sure that you respond to reviews, make changes to your PR as suggested by the reviewer and ask for clarification questions if needed.
This would make sure that you and the reviewer are on the same page and would make the PR reviews much easier.
Sometimes discussions can get really long! But these are necessary when you are adding a new feature with breaking changes
Tip 8: Be Patient
Most of the Open-Source maintainers are volunteers. They maintain projects during their free time off from their work.
So, they may take some time to get to your PR and review it.
So be patient while they do their thing. Take a break, drink a cup of coffee and watch Naruto.
Bonus Tip:
I will be writing about Contributing to, Building, Scaling and Maintaining Open-Source projects here on the DEV Community as well as on Twitter and on my blog.
In this last year, I have went from a noob Open-Source contributor to:
- Building my own project and making it to the #1 Trending Repository on GitHub
- Maintaining 2 CNCF Projects and
- Working full-time in Open-Source
I would like to share everything I've learned to help as many people as possible who are interested in Open-Source.
So, follow along and may the source be with you!
This content originally appeared on DEV Community and was authored by Navendu Pottekkat
Navendu Pottekkat | Sciencx (2021-09-15T16:28:21+00:00) Pull Requests Like a PRO: Tips to Make High-Quality Pull Requests. Retrieved from https://www.scien.cx/2021/09/15/pull-requests-like-a-pro-tips-to-make-high-quality-pull-requests/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.