First off, why?

I just want to start off by saying that contributing to projects can be super rewarding. Maybe there’s this weird bug in a node module that you use at work that you’ve built around a fix for in your own application. If you can find a way to move that fix into the module, not only are you being a good open source citizen by not just consuming that module (at no cost to you or your company, but with all of the utility) but giving back time and energy to a tool or library that has saved your company both the time and resources not having to build themselves. You also can feel good about yourself knowing that every other person who uses that module in the future will be using your contribution! And maybe in 2150 when all software on the internet relies on that module (you know, like left-pad or something) you will truly have reached immortality and cheated death, living on in the electrical signals and wires of the networked world, like some 90s idea of some cyber god/entity. Anyways, where were we? Oh yeah, making some PRs on GitHub. There was a really amazing podcast on Maintainer’s Anonymous with Maggie Appleton discussing open source as a gift economy that discusses how open source can be viewed outside of a market economy or just a water faucet of endless free packages. It resonated with me as motivation for why contributing is one good way to reciprocate the benefit you (or your company) has received from open source software. Having your company sponsor maintainers of open source projects your product depends on is an even better form of reciprocation (maintainers gotta eat), but that’s for a different blog post.

The Journey

What should I know before I get started?

If you take one thing away from this, remember to treat other projects as you would a house that you’re a guest in. If some rando from the internet came to your house, was rude to you, and demanded you let them make changes to your house it’d be totally reasonable to kick them out.

“But I’m totally a chill person, I would never come across that way.”

And maybe you are, but to expand upon the guest in someone’s house theme imagine you visit a friend’s house and upon entering walk straight past an area full of shoes and straight into their living room. Your host is a little annoyed and asks that you take off your shoes before walking around their house. But you wear shoes in your house all the time, so not a problem right? Problem is you’re not in your house, you’re in their house and so far you’ve already started your visit on the wrong foot or shoe or sock or… whatever. Just because you think you’re being a good guest doesn’t mean you are by your host’s standards. What constitutes “not being a jerk” to you might not be the same for them. If only there was a way your host could’ve conveyed how they expected you to behave while you’re in their house…

Code of Conduct

Good news! There’s this thing called a Code of Conduct that a lot of repos have now. They usually have a layout of behavior they expect you to exhibit, as well as negative behavior that they as a project won’t tolerate from you. GitHub even has this nice feature where they provide you a link to one if it exists whenever you make a pull request for the first time on a project. This isn’t a EULA to blindly click through like when you installed iTunes. This is a guide for how you should (and should not) act when participating in this project. The maintainer or maintainers took the time to specify the behavior they expect, so take the time to read it and follow it.

For example, the Octokit organization has Code of Conduct markdown files in each of their repos.

“But this has nothing to do with writing code!”

In my experience, writing software (in both a job setting and an open source setting) involves equal parts, if not more, the ability to treat others with empathy and respect as it does writing the actual software.

How do I even get started?

This is probably the hardest part. How do I know what needs working on? A lot of repos use the standard Good First Issue and Help Wanted, which are used to annotate issues that are a good starting point for new contributors. These are a great starting point, because the maintainer has kept these around to introduce new people to contributing to the project. In larger projects these can be picked up pretty quickly by other people, so sometimes they can be a little hard to find unassigned. Don’t worry though, just because an issue doesn’t have one of these labels means that you can’t work on it, it just might require a little more of your time.

Commenting on the issue with your intent to work on it is also a good start. Someone may already be working on it or the issue might not even be valid anymore, so it’s good to check in with the maintainer before you spend time on a change.

Documentation!

As a new potential contributor, you are totally the right person to find places in the documentation that don’t quite make sense, or could have better examples, or could be more consistent. It can be easy for someone who knows all of the ins and outs of the project to have trouble explaining it to someone new. This is an example of the Curse of Knowledge, which basically means that once you know a lot about a certain subject, you can lose the ability to teach it to someone else. In terms of effort, there’s less upfront time investment than having to set up an entire environment for that codebase when updating documentation. A great way to improve documentation is to find a project that you actually use at work and think of a time you had to spend time figuring out why some aspect of it wasn’t working the way you expected it to work. Couldn’t figure out all of the options a function takes from the documentation or the project’s GitHub README? Had to go searching for why some feature wasn’t quite working the way you thought it would? If you had trouble, chances are other people spent time trying to figure that out as well. Adding extra clarification to a documentation site or a README can mean the difference between a module working as you expect it to and an hour-long (or more) trek through search results and help forums and source code.

Other considerations (style, linting, tests, CI/CD)

When making a code change, try to keep it relevant to the issue you’re fixing. If the project uses semicolons, but you have personally vowed to never use them again in your own projects, don’t remove them from every file you touch. Ideally the project has a formatter like prettier set up to run on pre-commit or in CI, but if not, don’t go rearranging someone’s project just because you happen to like things that way. You’ll likely be asked to revert those changes because the changes will be inconsistent with the rest of the codebase.

If the changes you make break existing unit tests make sure to fix them. The test suite is there to help automate testing each change for any regressions, so it’s imperative to keep it running. If you fix a bug and no there were no tests to catch that bug, you can go above and beyond and add some test cases for that fix to make sure it doesn’t break again!

Make sure to pay attention to the automated checks that run on your pull request. A lot of repos have some continuous integration pipeline through TravisCI or GitHub Actions or whatever that automatically runs your changes through a pass of lint checking, formatting, and unit tests (and sometimes even functional tests!). The time of the person maintaining the repo is just as valuable as yours, so those checks act as a baseline for them to spend time reviewing and giving you feedback. Ignoring those is a pretty surefire way to not get a response to your changes, or at the very least a delayed one.

The Review

After you’ve opened a pull request and made sure you don’t have any outstanding linting, formatting, or test failures, you’ll hopefully get a review from either the maintainer or some other contributors. It’s important to explain what your change does and why the change is being made. If your change is visual it definitely helps to provide some screenshots showing the before and after versions of the software with your fix.

Make sure to follow the Code of Conduct when responding to reviews and criticisms. It’s more than likely the maintainer will ask you to make sure changes to the pull request you originally provide. Don’t beat yourself up over not being perfect; as a new contributor you most likely don’t have the context and historical knowledge that a maintainer would have after working with this project for a prolonged amount of time.

From here there’s kind of two ways things can go. I’ll highlight the happy path first.

After a some back and forth comments and code changes your pull request is merged and you’re a contributor now! Yay!

Another path is that you make a pull request and don’t hear anything for a few days. That’s okay, maintainers are real people with jobs and families and hobbies and lives. Just like how you are volunteering to make some changes or fix some bugs, maintainers are volunteering to maintain the project! If you don’t hear back in a week post a follow-up comment in the pull request and hopefully they’ll see it and you can get some comments and your changes merged. If they don’t respond they might not have the bandwidth to review and merge your changes right now. DON’T spam them on twitter asking for a code review, DON’T email them; you don’t know their life, you don’t know what they’re going through personally at the moment. At the end of the day it’s just software, and software you’re volunteering for at that.

At the same time, if interacting with people who maintain the project leaves you feeling uncomfortable or you don’t feel like you have the time or fortitude to continue working on something at this time, it’s totally fine to walk away. Your mental and emotional health matters and you are absolutely under no obligation to to volunteer/give away work for free if you don’t feel able to or don’t want to. Remember to take care of yourself!

Where do I go from here?

I’d really recommend looking for issues labeled Help Wanted or Good First Issue in open source projects that you use in side projects or in projects at work. You’ll be more likely to get a response from a smaller project that is still somewhat active than trying to make your first PR on the React repo. A good resource for how to contribute and where to contribute to is https://opensourcefriday.com/#participate. Also if you feel comfortable doing so, ask your employer if you can set aside some time periodically to work on open source.

If you have any questions, or if you’ve had different experiences and think I could expand upon this in any way, feel free to reach out on twitter at @copperwall.