Getting Started: Contributing to Open-Source Software
What is open-source software?
Open-source software (OSS) is simply software in which the source code is accessible to anyone. Users can view the source code, make changes to the code, and redistribute it.
OSS may be licensed under a variety of licenses. The key, according to the Open Source Initiative, is that the license “must allow software to be freely used, modified, and shared”. Some popular licenses for OSS include the MIT License, GNU General Public License, and Apache License 2.0. You can find out what license a project is using by checking out looking for the LICENSE file in the root directory or checking out their README.md.
For more information on the definition and usage of OSS, visit the Open Source Initiative and poke around. OSI’s mission is “To promote and protect open source software and communities”.
Some well-known OSS projects include Atom, React Native, HTTPie, d3, and many more.
Why should I contribute?
Many OSS projects have robust, active communities. Contributing is a great way to get involved! OSS projects may have their own Slack or Discord communities, conduct weekly check-ins with members, participate in the Google Summer of Code, and more. Getting involved in an OSS community is a neat way to connect with others and give back to a project that you may use in your own code.
Additionally, contributing to OSS gives you an opportunity to gain experience working collaboratively with other developers. If you are someone who mainly works on your own projects, reading and working with code that others have written while collaborating on changes is an excellent learning experience and will help you grow as a developer. This real-world experience is invaluable.
Contributing to an OSS project will require you to adapt to the flow of using proper git hygiene, opening or commenting on repository issues, submitting pull requests, receiving feedback from other community members, testing, and more. You will also need to respect the rules, maintainers, and code-style of the existing project. All of this may sound overwhelming at first, but it will come easily once you have made it a habit.
How can I get Started?
You will often hear the following advice: if you are working with a package or library and find yourself wishing it had a particular feature, write the code yourself and submit a pull request. Generally speaking, this is good and practical advice. In this scenario your change is likely useful not only to yourself, but to others using the project as well.
However, for a beginner looking to make their first OSS contribution, you may find that advice to be a bit overwhelming. Let’s walk through a first-time contribution step-by-step to get you started. Please keep in mind that this is general guidance. Refer to a project’s contribution guidelines for more specific instructions.
- Find a project that is open to pull-requests and is first-timer friendly.
There are several resources out there that help connect programmers with OSS projects open to contributions. I will link some of them below under the ‘Resources’ heading. Some projects even tag certain issues as ‘first-timers only’ in order to save space for contributors who are less-experienced with making OSS contributions and who may not be as familiar with the project’s source-code. Many communities who encourage first-time contributions will advertise this in their README.md or CONTRIBUTIONS.md documents. I would recommend choosing a project written in whichever language or framework you are most comfortable with. Keep in mind that some projects will not accept pull-requests.
2. Read the guidelines for contributing.
This is important! Look for a CONTRIBUTING.md file in the root of the project’s repository. Read the document thoroughly. This document will often provide you with instructions on how the project accepts contributions, direct you to the code of conduct, and tell you how to report bugs or troubleshoot.
3. Read the code of conduct.
Many OSS projects provide a CODE_OF_CONDUCT.md in the root directory that all members of the community must abide by. This is to ensure that all community members have a safe, positive experience. Read the code of conduct and act accordingly. First and foremost, treat everyone you come into contact with while contributing respectfully.
4. Familiarize yourself with the codebase.
Take some time to familiarize yourself with the project’s code. This is a great skill to hone, so take your time to absorb the code-style of the project and the varying technologies the project uses. You will want to fork the project’s repository and ensure that you can run it locally. This may also include running tests in your local environment. If you run into problems, reach out to the project’s community for help. Often, there is a troubleshooting document or thread in which you can find help.
5. Look for an issue you can tackle, or open one of your own.
Once you’re comfortable with the project’s code, take a look at the repository’s open issues. Look out for issues tagged with ‘first-timers only’ or similar tags. I recommend selecting a simple issue for your first contribution. If you don’t find an open issue that you’re comfortable working on, see if you can create one of your own. It can be as simple as fixing a typo in the project’s documentation. If you do open your own issue, be sure to provide enough information for the project maintainers to clearly understand what it is you want to address. Some projects provide a template to be filled out by the creator when a new issue is opened.
6. Claim the issue.
After finding an appropriate issue, make sure to communicate with the community. Comment on the issue stating that you would like to work on it. If you have trouble, don’t be afraid to reach out to the project’s reviewers or maintainers for help. If any part of the issue is unclear, ask for clarification. This will prevent you from wasting your time, and make it more likely that your changes will be accepted to the project. Make sure to write your code on a new, descriptively-named branch.
7. Open a pull-request.
Feel free to open up a pull-request (PR) early. You should link your PR to the issue you’re working on by referencing the issue number in your PR. Make sure that your PR has a descriptive title. As you work on the issue, you can ask for changes to be reviewed by the project’s reviewers via the open PR. Some projects will also have continuous integration testing or linters that run on all PR code. This feedback allows you to make changes to your code as you go. Again, you will want to defer to the guidelines and practices of the particular project you are working on.
8. Ask for a review.
When your code meets the requirements of the original issue and any/all CI tests are passing, you might feel your code is ready to be merged into the project’s codebase. If this is the case, wait for a reviewer or maintainer of the project to review your code. Take a look at the project’s guidelines — you may need to tag someone in order to get them to review your code.
9. Accept feedback from reviewers.
Members of a project who review and approve PRs have a full picture of the project’s conventions, style, and priorities. Please accept their feedback with grace! If your PR is not accepted right away, it is likely that you can make changes that will improve the code’s chances of being accepted. Ask the reviewer for clarity if you’re unsure.
10. Get your first OSS contribution merged into the project’s codebase!
If all goes well, you will work with the project’s reviewers until your code is acceptable and ready to be merged into the project’s codebase. If you reach this point, congratulations! Sometimes, the reviewers will choose not to accept your code or implement the change that your pull-request proposes. If that happens, don’t be discouraged. Consider whether there is another issue that is a better fit for your skills and the project’s priorities at this time, or explore some other projects that are open to first-time contributions.
Resources
- First Contributions allows you to practice making a pull-request to an OSS project. This is a great resource if you’ve never submitted a PR before and want to gain some confidence.
- First Contributions’ project list is a list of projects that are open to contributions by first-timers. You can even filter by language.
- MunGell/awesome-for-beginners provides a list of OSS projects that are good projects for beginners to contribute to. The list is organized by language, and identifies which tags beginner contributors should look for when searching for an appropriate issue to work on. This is a great resource!
- Public Lab provides a really useful sample git workflow for contributing to OSS. Check it out! This sample workflow can be generalized and applied to contributing to almost any OSS project. Public Lab is also extremely friendly and encouraging to first-time contributors. Their best practices list is also worth reading.
- Code Triage exists to help connect developers with open-source projects that have issues needing to be addressed.
In Conclusion
Above all, be respectful of the projects you contribute to. Secondly, have fun! Contributing to open-source software is a great way to give back and gain experience collaborating with other developers. It may take a little bit of trial-and-error to find the best way to put your skills to use, but there is a place in OSS for everyone.
