Contributing to open source software is a great way to make a difference in the community and learn how to work on a team. As an open source maintainer, I love to work with new contributors and see the community grow in a positive way. But as I start to get more involved with open source projects, I have noticed a few common mistakes made by new contributors.
In this blog post, I will go over 7 commonly made mistakes by new contributors in open source projects.
Table of contents
- Ignoring the contributing documentation
- Picking up issues that are not available
- Not reviewing their own work before reviews
- Creating PR's for features that weren't asked for
- Creating non descriptive issues
- Creating non descriptive PR titles
- Ignoring pull request and issue templates
Ignoring the contributing documentation
The purpose of the contributing documentation is to help onboard developers that are interested in contributing to a new project. Strong open source projects will have well defined contributing documentation which will include the following items:
- how to setup the project locally
- commit message conventions
- pull request guidelines
- types of contributions that will be accepted
It is important that all developers read through this documentation so they will understand what maintainers are looking for. If you skip the contributing documentation, then you will probably end up creating a PR that wasn't needed or asked for. That usually leads to the maintainers having to close the PR.
If you find a project that you interested in contributing to, please take the time to read through the README and contributing documentation. If you have any questions, reach out to the maintainers and they will be happy to help you.
Picking up issues that are not available
One of the issues that I ran into during Hacktoberfest was having developers pick up issues that were already assigned to someone else. That contributor would then open a PR and ask for a review which resulted in me closing it.
I understand that as a beginner sometimes it is hard to find issues that you can work on. But if the issue is not available, do not start working on it hoping that the maintainers will accept your PR over someone else that was assigned to the issue.
If you are struggling to find good first issues, then I would suggest looking into these resources:
Not reviewing their own work before reviews
One of the things I noticed while maintaining repositories during Hacktoberfest, is that a lot beginners didn't look at the PR they were submitting for review. I found a good amount of spelling mistakes, syntax errors or features that weren't tested or working correctly.
Before you request a review from a maintainer, make sure to do a quick review on your own work and run those changes locally. You would be surprised by the amount of bugs and mistakes that accidentally slip through when you are initially working on an issue. But that second look at the PR can help you find those mistakes and make the PR even better.
Creating PR's for features that weren't asked for
As a maintainer, there were a few instances of developers creating PR's for features that we were not looking to add in the project. These developers meant well but unfortunately they had wasted their time making contributions that ended up getting closed.
If you have a new idea for a feature, please do not start working on and wip up a PR. Instead you should create a new issue for your feature request. At that point, a maintainer will get back to you and let you know if they want to proceed with your feature or not.
Creating non descriptive issues
When you are creating an issue, it is important that you provide as much detail as possible so the maintainers know how to best respond to you. For example, if you find a bug on the site, make sure to include details on how to reproduce the bug, as well as links, screenshots or videos when applicable. That will give the maintainer an opportunity to troubleshoot the issue and determine what the next best course of action is.
Creating non descriptive PR titles
One of the issues that I run into a lot as a maintainer are PR's with vague and general titles. Titles like "Updating Readme" or "Fixing bug" do not help the maintainer understand what you trying to accomplish with your PR. It is important that you have short descriptive titles that effectively communicate the changes you would like to make.
Ignoring pull request and issue templates
A lot of open source projects will have issue and PR templates setup to help ensure that contributors provides all of the necessary information. Issue templates will usually be broken up into different categories like Bugs, Features, Documentation, etc. As a contributor, it is important that you choose the appropriate issue template and fill out all of the required fields so maintainers will know how to help you.
Here is an example of a PR template:
# Description <!-- Please include a detailed summary of the changes made. Also please link the issue that this PR is fixing. --> Fixes # (issue) <!-- Please place an x in the [ ] to check off the type of change for this PR --> ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Chore items (this includes basic clean up of files, or updates to packages) - [ ] Updates to documentation <!-- Please make sure to go through the entire checklist before requesting a review. Place an x in the [ ] to check off all of the items completed --> ## Checklist - [ ] I have a descriptive title for my PR - [ ] I have linked the issue to this [PR](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) - [ ] I have run the project locally and reviewed the code changes - [ ] My changes generate no new warnings
As a contributor, it is important that you follow all of the checklist items to help ensure that your new changes do not accidentally break another part of the application.
Getting involved with Open Source software is a great way to starting work on a team and contributing in a meaningful way to real world projects. While there is a lot of learn with open source, please be mindful of these 7 commonly made mistakes by new contributors.
If you have any more commonly made mistakes in open source, please reply below in the comments section.
Oldest comments (5)
Thank you Jessica for sharing this list with a lot of great information!
Contributing does not mean just throwing code ad some repos to get a green box on our profile, but there are rules and guidelines to follow in order to make a proper contribution.
For example, spending a couple minutes reading the docs might save way more time than writing code that will not get accepted because the feature wasn't requested/validated first!
Thanks, I would like to suggest how to overcome this mistake in your next blog thank you so much this was worth reading
I was a maintainer for the first time this hacktoberfest and can 1000% agree that all of these things happened and I tried to be gracious and gentle with folks but it could be really tough to see this stuff over and over. And for both sides too - I felt so bad when someone put in effort for something but it was not for something worthwhile 😭
Thanks Jessica for sharing these great insights for contributing towards OSS projects.