This article was originally posted on my personal blog.
I’ve been a maintainer to a couple of repositories now that specifically aim to help beginners to learn how to contribute to open source and give them a chance. It’s been a great journey you can read about it in my other article How I Learned About Contributing to Open Source Projects By Creating One.
Through my time as a maintainer, I noticed the same mistakes beginners make or the same issues they get confused about. That’s why I decided to put it all in one article in the hopes that it helps any beginner out there looking forward to contributing to open source projects.
Read the Contribution Guidelines
Almost in every open-source repository, you’ll find a file called
CONTRIBUTING.MD. This file will hold all the rules of contributing to this repository, a guide to how to make changes, and how you can contribute. It is very important that you read it as it can save you a lot of time figuring out what you need to do and can make sure that your pull requests (or PRs) will be following all the guidelines of the project, which will save time for the maintainers to review it and provide the changes to be made.
Create a New Branch
The first step you need to do when contributing to a project is forking it so that you can make the changes and commit them. But a step a lot of beginners miss is that you need to create a new branch. Do not fork then make changes to the master branch. This is extremely helpful for maintainers as well and for the project as a whole.
Get Assigned to Issues Before Working On Them
This might be different in some open-source projects, but I think it applies to most. Usually, when contributing to a project, you’ll go to the issues section of the repository to see what help is needed. When you find an issue that you think you can work on, first make sure that it is unassigned, then comment on it asking to be assigned. A lot of contributors look over the fact that an issue is assigned to someone else, or forget to comment on an issue, which causes confusion when looking over PRs that resolve the same issue. To avoid that, comment on the issue first, get assigned then submit your PR.
Before Submitting A PR, Create An Issue
This one applies to when you find a bug or have an idea for an enhancement, and it is not in the issues section of the repository. A lot of contributors proceed to just fixing it and sending a PR. Sometimes when it’s something small like a typo fix it’s not a big deal, however, when it’s a big change, especially if it’s based on what you think is better, make sure to send an issue with the suggestion or bug report first. If the maintainers find that you are right, they’ll assign you the issue. If, however, they find it doesn’t work for this project for one reason or another, then they’ll close it and it will save both your time and theirs.
You Don’t Need to Create A New PR For Every Change
I’ve seen a lot of confusion about this. A contributor would send in a PR, I’d request changes, then the contributor proceeds to closing the PR and submitting the new one with the changes requested. You don’t need to do that.
When you want to make changes to a PR, just make the changes then commit them to the repository you sent the PR from. Let’s say you forked the repository and created a new branch
patch-1, then make changes in that branch and just commit and push your changes. The changes will automatically show in the PR.
Don’t Commit Unnecessary Files
I’ve received PRs that include commits to files that are not necessary for the project, like your IDE’s configuration files. Before committing your changes, look at what has changed and only commit what applies to the issue you are working on.
Don’t Be Discouraged
My favorite contributor was actually someone who messed up a lot. The reason behind that is that they kept telling me they were a beginner and they made a lot of mistakes, so I had to keep asking them for changes. I honestly thought at some point that they’ll close the PR and just quit. However, they kept trying and with time not only did they provide the needed result, but also contributed to other issues as well. It’s ok to make mistakes in the beginning, it’s how you learn to do better next time.
If you’ve never contributed to open-source projects or you are hesitant about it, you should start now. It’s very important and will help you a lot by giving back to the community. Look at the tips above to help you and start with easy projects. Even small contributions that you can make will help.
Originally published at https://blog.shahednasser.com on February 28, 2021.