This post is part of a 3-part series titled “Making your first open source contribution”:
- Making your first open source contribution, part 1 - finding projects, issues, and mentored programs
- Making your first open source contribution, part 2 - before you start contributing
- Making your first open source contribution, part 3 - navigating new codebases
Congratulations! You’ve found a project and issue that you will be working on. 🥳 Before you jump into making your first contribution and making a pull request, there are several things that you need to do first.
Read the README
The README contains everything that you need to know about a project. Since the README is the first entrypoint for everyone—from users to potential contributors—it usually covers a wide range of things: what is this project? Where do things go? How do you use it? Where is the contributing guide? What files you should look at first? How to reach out to the maintainers or community should you have any questions?
Some information that is specifically aimed at contributors might be hosted elsewhere. I’ll get into this later.
Read the code of conduct
A code of conduct establishes expectations for behavior for a project’s participants 1. In a code of conduct you might find information such as:
- what behaviors are encouraged
- what behaviors are unacceptable
- procedures on what to do when something inappropriate happens & who to contact
Code of conducts help to ensure a safe & inclusive environment. Always make sure you check out the code of conduct first before participating in the community.
Read the contributing guide
The contributing guide is usually located in a file called CONTRIBUTING.md. If you can’t find the file, don’t worry! Not every project hosts their contributing guide in GitHub. For example, pandas hosts its contributing guide in its documentation website. The link to the guide is usually linked somewhere in the README.md for visibility. Smaller projects may have their contributing guide in the README.md.
A contributing guide usually outlines steps that you need to do when you’re contributing. This may include things such as:
- How to open up a new issue: maintainers typically encourage people to open up a new issue before they start contributing, if the issue does not yet exist. Some projects also have issue templates that you have to fill out properly. This issue in the Go repository is an example of issue that uses a predefined issue template.
- How to set up the development environment: every project requires a different setup. Some projects, like pandas, requires you to build it from source so you can test out the code changes.
- Code standards or style: before writing your code, you need to get familiar with the style guide, linters, and other tools that the project uses to keep their code consistent & easy to read. Some projects like Rust already has a script that makes sure your code is consistent with Rust’s guidelines, which you can find in their CONTRIBUTING.md.
- Tests: while most projects already have CIs set up to check your code, you might want to avoid comitting your changes without really knowing whether they will pass the test or not, so it’s best that you know how to test your code locally.
- Specific instructions on writing commit messages: some projects, like pandas, have conventions on writing commit messages.
- Pull request workflow: every project has a different workflow for pull requests. By familiriazing yourself with this, you will know what to expect when submitting your pull request. Some projects have a bot that help maintainers to assign reviewers, and these bots might request you to add some more information if needed. A few projects such as Kubernetes require you to sign a Contributor License Agreement (CLA) if it’s your first time contributing to the repository. Another thing is that once you submit your pull request, you might encounter merge conflicts, and some projects like Rust have a specific policy regarding whether you should rebase or merge.
Browse around the repository
Take a look around the repository & notice how people usually open issues & write pull requests. You might also want to take notes on how the maintainers respond to people who are contributing to their project. If it seems that the environment has a negative atmosphere, or if you notice that issues and pull requests are not being responded to, it’s probably best to redirect your time and effort elsewhere.
Whew. It might seem like a lot, but I actually find comfort in reading these READMEs, Code of Conduct, & contributing guides—they are here in your best interest to ensure that you have a good experience contributing to their projects. Before contributing to a new project, I personally enjoy perusing through every guide I can get my hands on. It might take a while—for large projects, it might take me an entire day to really wrap my hand around it—but it does save a lot of time later when I’m at a point where I’m writing my code, making pull requests, & getting my pull requests reviewed.
If you get confused, make a mistake, or feel like there are missing steps, don’t worry! These guides are not perfect, & it’s possible that they do miss some essential information. This is an opportunity for you to open a new issue and make a pull review to help the next person, because really, chances are other people will get confused over the same thing, too.