Category: pull request

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.

Ask first

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.

Use labels

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.

The post How to Contribute to an Open Source Project appeared first on CSS-Tricks.