How to contribute to an open source project on GitHub

A step by step guide that will show you how to contribute to an open source project on GitHub, one of the most popular and used git repository hosting services.

How to contribute to an open source project on GitHub

GitHub is the home of many popular open source projects like Ruby on Rails, jQuery, Docker, Go and many others.

The way people (usually) contribute to an open source project on GitHub is using pull requests. A pull request is basically a patch which includes more information and allows members to discuss it on the website.

This tutorial will guide you through the whole process to generate a pull request for a project.

1. Choose the project you want to contribute to

If you decided to contribute to an open source project on GitHub it’s probably because you’ve been using that project and you found a bug or had an idea for a new feature.

You can also explore featured and trending projects on GitHub or use the website search to find something in particular. When deciding to contribute to an open source project make sure to check it’s still active otherwise your work might remain a pull request forever.

If you don’t have a feature or bugfix in mind you can check out the issues section of a project to find open tasks. It’s often useful to filter them using the labels created by the mantainers to find out available tasks not assigned to anyone yet.

GitHub project issues

Sometimes mantainers highlight easy tasks to encourage new contributors to join the project, like for example the one tagged “easy fix” in libgit2.

Before proceeding with the contribution you might want to check the (software) license of the project, just to make sure you are happy with its requirements.

2. Check out how to contribute

This is a very important step as it will avoid you (and the project mantainers) to waste a lot of time trying to help a project in a wrong way.

For example some popular projects like the Linux kernel and git use GitHub as a mirror, but they don’t consider any contribution received on GitHub.

Once you are on the main page of the project you want to contribute to look for notes and files that explain how the mantainers expect you contribute to the project.

how to contribute

Often there’s a dedicated file with detailed instruction called CONTRIBUTING.md, but sometimes you’ll find notes in the README.md file which is displayed at the bottom of the page as well.

Before starting to work on your contribution, It’s a good idea to check out existing issues and pull requests to be sure you’re not going to do something which is already being done by someone else.

At this stage you might also open an issue to check if mantainers are interested in what you’re going to work on.

3. Fork the project

Once you have established that the project accepts pull requests and that your feature/bugfix has not already been taken, it’s time to fork the project.

Forking the project creates a personal copy which will appear in your GitHub profile. to fork a project on GitHub simply click the Fork button on the top-right corner of a project page.

fork GitHub project

4. Clone the forked project

After you forked a project you need to clone it to have a copy on your machine you can work on.

To clone a forked project go to the repositories section of your GitHub profile and open it. There you can click on the “clone or download” button to get the address to clone.

GitHub project clone or download button

GitHub gives you 2 protocols to clone a project: HTTPS and SSH. For more details about which one to use check out their detailed guide on the topic. From now on let’s assume you decided to use HTTPS.

Once you have copied an URL you can clone the project using a git client or git in your shell:

$ git clone https://github.com/YOUR_USERNAME/PROJECT.git

Cloning a project will create a directory on your disk which contains the project and all the files used by git to keep track of it.

5. Set up your cloned fork

Enter the cloned directory and add the URL of the original project to your local repository so that you will be able to pull changes from it:

$ git remote add upstream https://github.com/PROJECT_USERNAME/PROJECT.git

I used upstream as remote repository name because it’s a convention for GitHub projects, but you can use any name you want.

Now listing the remote repositories will show something like:

$ git remote -v
origin https://github.com/YOUR_USERNAME/PROJECT.git (fetch)
origin https://github.com/YOUR_USERNAME/PROJECT.git (push)
upstream https://github.com/PROJECT_USERNAME/PROJECT.git (fetch)
upstream https://github.com/PROJECT_USERNAME/PROJECT.git (push)

6. Create a branch

Before starting to work on your feature or bugfix you need to create a local branch where to keep all your work. You can do that with the following git command:

$ git checkout -b BRANCH_NAME

This will create a new branch and will make it the active one in your local repository. Be sure to use a descriptive name for the branch name.

You can check you are in the right branch using git:

$ git branch
  master
* BRANCH_NAME

The current active branch is the one with a * on the left.

7. Work on your contribution

Now it’s time to work on the project. It’s very important you keep this very specific and focused on a single feature or bugfix. Trying to squeeze multiple contributions in a single pull request means chaos because it makes it impossible to handle them separately.

While working on your contribution make sure to pull changes from upstream (the original project) frequently or at least before pushing your changes to origin (your fork). That will force you to fix any possible conflict before submitting your pull request to the project.

8. Create a pull request

Once you finished to work on your contribution it’s time to push it to your forked repository on GitHub:

$ git push origin BRANCH_NAME

Now go back to your forked project on GitHub in your browser and you will find a new button at the top of the page to create a pull request:

GitHub compare & pull request button

Click the button and you will get a new page which contains all the information on your pull request and where you can submit it to the original project.

Before finalising the pull request make sure to have checked everything is fine and to include as much information as possible to help the mantainers of the project understand what you have done and why.

9. Follow up

Hopefully some of the project mantainers will check your pull request and will give you feedback or notify you they decided to merge your changes soon. They might also ask you to change something or decide not to use your contribution. Anyway everything will be discussed on GitHub and you will receive notifications via email every time someone comments your pull request.

10. Clean up

After your contribution has been merged to the main project (or rejected) you can delete the branch you used for it.

To delete the branch in your local repository:

git branch -D BRANCH_NAME

To delete the branch on GitHub:

git push origin --delete BRANCH_NAME

Conclusion

I hope you enjoyed this tutorial explaining how to contribute to an open source project on GitHub. If you have any question feel free to leave a comment.

If you found it useful feel free to share it on social media using the social buttons below.

Subscribe

Don’t forget to subscribe to the blog newsletter to get notified of future posts.

You can also get updates following me on Google+, LinkedIn and Twitter.

22 Comments

  1. Sverrir Sigmundarson

    Excellent guide, but missing one very important and complicated aspect that is crucial.

    How do you successfully update your fork and then your feature branch while still retaining your change commits when the upstream branch changes?

    Add that and this is pretty much complete.

    Reply
    1. Kasim

      You fetch upstream from time to time and rebase your feature branch against upstream/master before pushing/time to time.

      To keep your fork updated:

      You fetch upstream and merge upstream/master into your origin/master, then push origin master.

      Typically, you don’t need to keep your fork updated if the goal is to contribute to the main repo.

      Reply
  2. Stefan Gloutnikov

    Great article! Only thing maybe to add is how to pull new changes from the original project into your local master, if there have been any since originally cloned:
    ‘git fetch upstream’
    ‘git checkout master’
    ‘git merge upstream/master’

    Reply
  3. Milosh Bilosh

    Great article. I’ll definitely reference it to Github newcomers.

    Reply
  4. Andrew Ribeiro

    I’ll pass this out to some people that I always have to go over this with. Thanks for the article.

    Reply
  5. David Phillips

    You can update your local branch using this command: git pull –rebase upstream master

    Reply
  6. Pd

    Point 1 should be Choose not Chose.

    Reply
  7. Adnan

    Awesome. Short and sweet. No useless nonsense.

    Reply
  8. Lalit Kale

    You didn’t have to even search github. There is http://up-for-grabs.net/ with which you can find the project where you can contribute your first commit. Just my 2 cents..

    Reply
  9. Adnan Siddiqi

    @Lalit: Interesting Website!

    Reply
  10. Patrick Masson

    I’d recommend adding something about checking that the license is actually an OSI Approved License. I did a quick review of the featured and trending projects on GitHub and a few were not assigned open source software licenses, another mentioned a license but did not include it with the source, and a few (e.g. universalcore/elastic-git / https://github.com/universalcore/elastic-git) were not licensed at all–meaning that the work is actually, “all rights reserved,” and cannot be copied/used with our express permission of the copyright holder.

    It might be kind of a drag, but understanding licensing is the first part of contributing to a project. Even if a license is present, contributors will want to be sure that their work (and expectations) are in line with those of the original author, for example, copyleft and permissive licences and the ramifications of such.

    Thanks for the post,
    Patrick

    Reply
    1. Davide Coppola (Post author)

      Good point. I added a quick note in the first paragraph.

      Thank you for pointing this out.

      Reply
  11. Roshan

    I’d started on a project to help first time contributors to start contributing right away. The tutorial is a hands on one. Could you give me your feedback about that?

    Reply
    1. Roshan
    2. Davide Coppola (Post author)

      It would be better adding more headers to highlight what the paragraphs are about like in my guide.

      Also mentioning how to stay in sync with the main repo shouldn’t be at the end, but before starting with the contribution work.

      Reply
      1. Roshan

        Thank you for your feedback Davide

        I’ll be adding headers to provide a better step by step organisation for the tutorial

        I’m not sure if syncing part should be in the beginning. I wanted my users (my target audience is people who are doing open source contributions for the first time) to try on something and get value as quickly as possible. That was why I had least explanation about what is being done. Could you explain why you suggested me to put in on top?

        Reply
        1. Davide Coppola (Post author)

          Because, as I mentioned in my guide, you need to make sure your local branch doesn’t create any conflict with the main project before generating a pull request.

          Syncing AFTER generating a pull request is just bad practice and might be trouble.

          Reply
  12. jayson Mathew

    cool and awesome description and knowledgeable

    Reply
  13. Chris G

    Great article, but Kent C. Dodds free Egghead.io tutorial is a little bit more comprehensive IMHO

    https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github

    Reply
    1. Davide Coppola (Post author)

      it seems it is, but I honestly don’t like video tutorials for anything dev-related. Too fragmented and time consuming.

      Reply
      1. Chris G

        Not these. Kent does a great job. but to each his own for sure 🙂

        Reply
        1. Davide Coppola (Post author)

          I am sure he’s doing a great job.

          I was referring to video tutorials in general. I don’t believe they work for dev material because:
          – you can’t fast read
          – you can’t search
          – you can’t copy&paste

          no matter how good they are.

          But this is just my opinion of course and, as you said, I am sure some people find them useful/better.

          Reply

Leave a Comment

Your email address will not be published. Required fields are marked *