How to contribute to an open source project

There is a world of advantages in contributing to open source projects. You improve the projects you love, enhance your skills, build a portfolio, have mentors, and learn people skills. However, you might still wonder exactly how to contribute to open source projects.

While each project is unique and has its characteristics, the patterns are the same across different open source repositories. Knowing these similarities, we provide a guide to open source contributions.

Know Git fundamentals

To contribute to open source projects, you need to have experience with version control because most projects are hosted on a version control repository, like GitHub, Bitbucket, and GitLab.

As such, you need to understand the essential Git commands. GitHub provides a helpful Git cheat sheet if you need to refresh your knowledge.

Understand the anatomy of the project

Understanding the code of an open source project is the most challenging task new contributors face. Beginners often try to understand the entire codebase at once, which will confuse you.

A  good open source project has rich documentation to help new joiners navigate the project. These files are usually at the top level of a repository:

• README.md – introduces the project, its purpose, and basic installation requirements;
• CONTRIBUTING.md – gives clear instructions on how to contribute to the project;
• ROADMAP.md – shares the vision for the project and the tasks that need to be done;
• LICENSE.md – provides information on the reuse and permissions associated with the code;
• Other documentation – tutorials, guides, or governance policies, depending on the project.

Although not all open source projects have CONTRIBUTING or ROADMAP files, having this documentation indicates how friendly and welcoming a project is. 

After checking these files, try to understand the project structure: learn about file and folder hierarchy and their naming structure. Finally, take some time to understand the project’s coding style and coding standards.

Checklist before you contribute

Here’s a handy checklist to evaluate whether a project is good for new contributors. Check the project and answer the following questions:

• [Basics] Does the project have an open source license? 
• [Basics] Does the project actively accept contributions?
• [Commit activity] When was the latest commit?
• [Commit activity] How many contributors does the project have?
• [Commit activity] How often do people commit to the project?
• [Issues] How many open issues are there?
• [Issues] Do maintainers respond quickly to issues when they are opened?
• [Issues] Is there active discussion on the issues?
• [Issues] Are the issues recent?
• [Issues] Are issues getting closed?
• [Pull requests] How many open pull requests are there?
• [Pull requests] Do maintainers respond quickly to pull requests when they are opened?
• [Pull requests] Is there active discussion on the pull requests?
• [Pull requests] Are the pull requests recent?
• [Pull requests] How recently were any pull requests merged?
• [Welcoming] Do maintainers thank people for their contributions?
• [Welcoming] Are people friendly in the issues and discussion forum?

How to submit a contribution

Communicating effectively

Working with others is one of the most critical skills you’ll develop in open source. So before you open an issue or pull request, keep these in mind:

• Give context. If you’re running into an error, explain what you’re trying to do and how to reproduce it. If you’re suggesting a new idea, explain why it would be helpful to the project.
• Do your research first. Before asking for help, check a project’s README, documentation, and issues (open or closed). People will appreciate it when you show that you’re trying to learn.
• Keep requests short and direct. Every contribution requires someone else’s review. Many projects have more incoming requests than people available to help, so be concise. That way, you’ll increase the chance that someone will be able to help you.
• Keep all communication public. Don’t contact maintainers privately unless you need to share sensitive information (e.g., security issues). More people can learn and benefit from your exchange when you keep the conversation public.
• Ask questions, but be patient. Don’t forget that even longtime maintainers are not always familiar with every part of the project.
• Respect community decisions. Your ideas may differ from the community’s priorities. As a result, they may offer feedback or decide not to pursue your idea.
• Always assume good intentions. Open source has collaborators from all over the world, and sometimes context gets lost across languages, cultures, and backgrounds. Be patient, and remember that written communication makes it harder to pass a tone.

Finding and solving issues

In GitHub, every repository has an issues tab, where you can see current problems, bugs, and issues. If the repository is well-maintained, it will also have labels to help you filter the problems. Here are some tips for communicating on issues:

• If you see an open issue that you want to tackle, comment on the issue to let people know you’re on it. That way, people are less likely to duplicate your work.
• If an issue was opened some time ago, it’s possible that it’s being addressed somewhere else or has already been resolved, so ask for confirmation before starting working.
• When opening an issue, you should include steps to replicate. This helps developers identify the problem and start working on fixing it.
• If you opened an issue but figured out the answer later, comment on the issue to let people know, and then close it.

Opening a pull request

Now that you have solved an issue, it’s time to open a pull request. Project maintainers will view your changes, and your code will be merged into the base branch when approved. Here are some tips for when opening a pull request:

• Run your changes against existing tests, and create new ones when needed.
• Write commits according to the issue you solved.
• Reference relevant issues or supporting documentation (for example, “closes issues #22”).
• Include screenshots of the before and after (if applicable).
• Contribute by following the coding style and standards of the project.

What happens after you submit a contribution

You don’t get a response

Did you check the project for signs of activity? Still, you might not get a response even on active projects. If you haven’t gotten a response in over a week, you can reply in the thread, asking someone for a review. If you still don’t get a reply, nobody may respond.

There are many possible reasons you didn’t get a response, including personal circumstances that may be out of your control. Don’t get discouraged; try to find another project or way to contribute.

Your contribution doesn’t get accepted

Maintainers may not accept your contribution. You can ask the maintainer for feedback and clarification if you’re unsure why. Ultimately, however, you’ll need to respect the decision. Don’t argue or get hostile, and thank maintainers when they put effort into helping you. In the end, you’re always welcome to fork and work on your version if you disagree with the decision.

Someone requests changes to your contribution

It’s common for maintainers to ask you to make changes. If that happens, be responsive. After all, they’ve taken the time to review your code. On the other hand, if you don’t have time to work on the issue, let the maintainer know so they’re not expecting a reply, and someone else can take over.

Your contribution gets accepted

Congratulations, you did it! You’ve successfully made an open source contribution! So whether you just made your first open source contribution or it’s your 100th time, enjoy the moment.

[Live Talk] Maintaining Code Quality in Open Source

Would you like to hear an expert dive deeper into open source project management? Join Codacy CEO Jaime Jorge in an exclusive talk with Neils Lohmann, founder of the JSON for modern C++ on GitHub.