How to Contribute to an Open Source Project

• Contribute, Source

8 min. (1537 words)

how-to-contribute-to-an-open-source-project

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:

Shows a referenced issue on a <abbr>PR</abbr>” loading=”lazy” src=”https://css-tricks.com/wp-content/uploads/2019/08/Screen-Shot-2019-08-24-at-10.55.24-AM.png” ></img></figure> <p>In the Issue:</p> <figure id=Shows what the reference looks like 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.

38 comments

  2. This paragraph offers clear idea in favor of the new visitors
    of blogging, that genuinely how to do blogging.

  3. Do you have a spam problem on this site; I also am a blogger, and
    I was wanting to know your situation; many of us have created some
    nice procedures and we are looking to trade techniques with others, be sure to
    shoot me an e-mail if interested.

  4. I have read so many content on the topic of the
    blogger lovers but this piece of writing is
    in fact a fastidious piece of writing, keep it up.

  5. I seriously love your blog.. Pleasant colors & theme. Did you develop this site
    yourself? Please reply back as I’m attempting to create my own personal blog and would love to
    know where you got this from or what the theme is named.
    Thanks!

  6. I just couldn’t depart your site prior to suggesting that I actually
    loved the usual info a person provide to your guests? Is
    gonna be again incessantly in order to check up on new posts

  8. Thank you for the auspicious writeup. It in fact was a amusement account it.
    Look advanced to far added agreeable from you! By the way, how
    could we communicate?

  9. This design is incredible! You most certainly know how
    to keep a reader amused. Between your wit and your videos, I
    was almost moved to start my own blog (well, almost…HaHa!) Wonderful job.

    I really enjoyed what you had to say, and more than that, how you presented
    it. Too cool!

  10. Hi there! This blog post couldn’t be written much
    better! Going through this post reminds me of my previous roommate!
    He constantly kept talking about this. I most certainly will forward this article to him.
    Fairly certain he’ll have a good read. Thank you for
    sharing!

  13. With havin so much content and articles do you ever run into any problems of
    plagorism or copyright violation? My site has a lot of exclusive content I’ve either written myself or
    outsourced but it seems a lot of it is popping it up all over the
    internet without my permission. Do you know any methods to help prevent content
    from being stolen? I’d really appreciate it.

  14. Everything said was actually very logical. But, what about this?
    what if you added a little information? I am not saying your
    information is not good., however suppose you added a headline
    that grabbed a person’s attention? I mean How to Contribute to an Open Source Project – Pavvy
    Designs is kinda boring. You should peek at Yahoo’s front page and see how they
    create post titles to grab viewers to click. You might add a video or a related pic or two to get readers
    excited about everything’ve written. Just my opinion, it
    would bring your posts a little bit more interesting.

  15. I’m gone to inform my little brother, that he should also visit this weblog on regular basis to get updated from
    hottest news update.

  16. It’s really very difficult in this busy life to listen news on Television, so I only use world wide web for that reason, and obtain the
    latest information.

  17. Excellent weblog right here! Additionally your site lots up very fast!

    What host are you the use of? Can I am getting your affiliate hyperlink on your host?
    I want my site loaded up as fast as yours lol

  18. Magnificent goods from you, man. I have understand your stuff previous to and you’re just extremely magnificent.
    I actually like what you have acquired here, really like what you’re stating and
    the way in which you say it. You make it entertaining and you still
    care for to keep it sensible. I can’t wait to read far more from you.
    This is really a terrific website.

  21. I am curious to find out what blog system you are working with?

    I’m having some small security issues with my latest website and I’d like
    to find something more risk-free. Do you have any suggestions?

  22. I don’t even understand how I stopped up here, but I assumed this submit was once great.
    I don’t recognize who you are however certainly you’re going to a famous blogger in the event you aren’t already.
    Cheers!

  23. My developer is trying to persuade me to move to .net from PHP.
    I have always disliked the idea because of the costs.
    But he’s tryiong none the less. I’ve been using WordPress on several websites for about a year and am nervous about switching
    to another platform. I have heard great things about blogengine.net.

    Is there a way I can import all my wordpress content
    into it? Any help would be really appreciated!

  24. Good post. I learn something totally new and challenging on sites I
    stumbleupon everyday. It’s always exciting to read articles
    from other authors and use a little something from other websites.

  26. Aw, this was a very nice post. Takiong a few minutes
    and actual effort to make a really good article… but what can I say… I put things off a lot and don’t seem to get nearly annything done.

    Visit myy website Chaturbate

  29. Nice post. I learn something totally new and challenging on sites I stumbleupon every day.
    It’s always useful to read articles from other writers and practice a little something from their sites.

  33. Right here is the right website for everyone who hopes to understand this topic.
    You understand so much its almost hard to argue with you (not that I actually would want to…HaHa).
    You definitely put a new spin on a topic which has been discussed for a long time.
    Wonderful stuff, just wonderful!

  36. Write more, thats all I have to say. Literally,
    it seems as though you relied on the video to make your point.
    You obviously know what youre talking about, why throw away your
    intelligence on just posting videos to your weblog when you could be giving us something enlightening to read?

  38. Howdy just wanted to give you a quick heads up. The text in your post
    seem to be running off the screen in Chrome. I’m not sure if this is a formatting issue or something to
    do with web browser compatibility but I figured I’d post to let you know.
    The layout look great though! Hope you get the problem resolved
    soon. Many thanks

Leave a Reply

Your email address will not be published.