The following is going to get slightly opinionated and aims to guide someone on their journey into open source. As a prerequisite, you should have basic familiarity with the command line and Git. If you know the concepts and want to dive right into the step by step how-to guide, check out this part of the article.
Truly, there is no one way to contribute to an open source project, and to be involved often means more than code slinging. In this article, though, we’re going to focus on the nitty-gritty of contributing a pull request (PR) to someone else’s project on GitHub.
Let’s set the stage…
You come across someone’s project on Github and you love it! You may even decide to use it in your own project. But there’s one small thing you notice… it could be a bug. It could be an enhancement to what’s already there. Maybe you looked through the code and found a nice, optimized way of writing things that’s a little more legible, even as small as an extra indentation in the code.
Here are some initial suggestions and instructions on where to go from here.
Look for a
CONTRIBUTING.md document or Contributing Guide in the documentation
Many open source projects know that other people might want to contribute. If they find themselves answering the same question again and again, this document intends to make it easier to get everyone on the same page.
Some things you might find in a Contributing guide:
- Style guidelines
- Prerequisites for submitting a PR
- How to add your change to their documentation
- A checklist for contribution
- Explaining the project’s architecture and setup
This document can be as simple as a few notes, or it can be so robust that it takes you a little while to read through it all (like Atom’s Contributing guide, for example).
For larger projects, it makes sense to communicate contributing guidelines up front because PRs and issues can pile up and be a real drag on a maintainer’s time, sorting through contributions that might be out of the project’s scope. Make sure to take some of your own time reading through this guide if it exists because your PR will require some of the maintainer’s time as well.
Look through the existing issues and PRs
Before adding a new issue or submitting a PR, it’s good to check what else is out there. You might find someone has already asked about the same thing, or submitted something similar. You can check in the project’s search box — I usually search through issues that are both open and closed, as it’s important to know if someone already raised my concern and perhaps the maintainer decided to go in another direction. Again, it’s about saving both you and the maintainer time.
Submit an issue
Submitting issues is a core part of the PR submission process. They provide an opportunity to articulate the situation, establish context around it, and provide a forum for discussion that can be attached to the PR itself.
When submitting an issue, I like to write out what my concern is and then re-read it as if I was on the receiving end. People are human — even if what you say is technically correct, you’re not likely to get buy-in for your idea if your tone is off-putting. Consider this: you may be asking for someone to do a lot of work in their spare time. If someone asks you to do work on a Saturday, are you more likely to do so if they ask respectfully with condescension? You get the picture.
When submitting an issue, make sure you give them all the details they need to get the work done. Some things you might note:
- If it’s a bug, then what environment you’re seeing the problem in? Is it development or production? Perhaps somewhere else?
- If it’s a feature request, then explain the problem. Sometimes framing this from the perspective of the end user in the form of user stories can be helpful, both to conceptualize the situation and abstract it from any personal feelings.
- If it’s a general question, then state that up front so the maintainer can avoid spending time trying to figure out if you’re asking for a bug or a feature.
- If you’d like to submit a PR to improve on the issue, mention that you’d like to do this, then ask permission to proceed (because sometimes maintainers have other items planned you may be unaware of).
Make considerations before starting work
You’re probably eager to start working on your PR by this point. But first, there are still a few customary things to check off before you dig in.
I’m a big fan of people asking in an issue if a PR makes sense before they work on one. I don’t hold it as a strict rule, but sometimes I can save them buckets of time and going in the wrong direction if we can clarify what we both want together first. It also helps others know to not implement the same thing (assuming they, too, look through open and closed PRs.
If you do submit an issue and everyone agrees a PR is a good idea, then it’s nice for you (or the owner of the repo) to add the label in progress. You can search labels so it’s really clear to everyone you’re working on it.
Work in small chunks!
As a maintainer, it’s frustrating when someone put in a lot of work and submits a giant honking PR that does 10 different things. It’s really tough to review, and inevitably, they’re doing six things you want, and four things you don’t. Not only that, it’s usually spread out over multiple files which is difficult to untangle. I’ve definitely closed PRs with some high-quality code I would like just because it would take forever for to review and manage it. (I will communicate that this is the issue if they would like to resubmit the work as separate PRs, though.)
In my opinion, you have about 1,000% more chance of getting your PR merged and your time spent honored if you split things over multiple, smaller PRs. I love it when people submit a PR per topic. And it can be nice, not required, if each submission is a little spaced out as well to help with the cognitive overload.
Submit your PR
These are the steps I personally use to submit a PR. You can get this done other ways, of course, but I have found the following to be effective in my experiences. Also, anything in the commands that are written in ALL CAPS is information you will need to change for your use.
First off, go to the repo, and fork a copy of the project to your personal GitHub account. Clone it locally and change directory (
cd) to where it’s located. (I use HTTPS, but SSH is totally fine as well.)
git clone https://github.com/YOUR-USERNAME/YOUR-FORKED-REPO.git cd into/cloned/fork-repo
Next up, add a remote upstream to the original branch. This means it will share a connection with that original branch so that you can keep in sync and pull down any updates to the project when they happen.
git remote add upstream https://github.com/ORIGINAL-DEV-USERNAME/REPO-YOU-FORKED-FROM.git git fetch upstream
Now you can create a new branch and give it a name that relates to the PR topic. Note that a maintainer might have a specific naming convention in mind that is documented in the repo.
git checkout -b GOOD-FORKIN-NAME
Go forth and work on your changes. Be sure to make good commit messages along the way:
git add -A git commit -m “ADDING IN A TACO DISPENSER” git push origin GOOD-FORKIN-NAME
GitHub will see the new fork and prompt you to make the PR, which is a nice, helpful touch. You click the button and fill in details: what issue does it close? you can refer to them by their number and GitHub will automatically associate it:
On the PR:
In the Issue:
What are some of the things to note in the PR? These details help the maintainer understand context. These can be all the changes you made, they can be larger strategy or context.
And you’re on your way! 🎉
You may find you need to keep your fork up-to-date with the remote, and pull their changes into yours. To do so, you would run this command:
git pull upstream master
Props to Christina Solana for her Gist which I’ve used as a reference for years and years now.
Always remember: maintainers are often swamped, sacrificing nights and weekends to keep open source projects active and updated. Being respectful, both in terms of their time, and in tone, can set you up for success in contributing.
Open source can be extremely rewarding! Knowing other people are benefitting and directly using something you contributed can be a great way to give back to the community and learn.
For minor corrections using a git client can be overkill and this is literally why github has a web interface that lets you fork, edit and submit pull requests without downloading a half-gig’s worth of project.
Very helpful, thanks! I’m using the latest and greatest tools like IntelliJ and GitHub Desktop, but had to puzzle through the UI a bit to find out how to get the changes from the ‘upstream master’ back to my local copy, and this did the trick in one line. I know there are the folks that prefer clicking buttons, but the command line techniques shown here are concise, powerful and fast, and the way to go as you get more experienced. Oh, and “minor corrections” – do make sure to test those, especially if want to stay on the good side of the maintainer, that’s why downloading half a gig and following the instructions on this page might be worth it :)
Thanks! Your tips were really outstanding and have helped me a lot to notice some things I’ve done wrong when trying to help with some open source project. Thanks too for the time you spent writing this article!
Hey, cool article! About the forking process, I used to do it the way you propose here. Then a colleague of mine gave me some advice to clone the host repo (so origin is the repo you fork from) and then just add your fork as a remote (I usually call it my firstname). That way it’s easier to stay synced to the latest origin. Then when you create a branch, all you need to do is make sure you push to the right upstream (your fork). I found this flow to be a lot easier to work with.