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.
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. Chose 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.
Sometimes mantainers highlight easy tasks to encourage new contributors to join the project, like for example the one tagged “easy fix” in libgit2.
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.
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 (open) issues and pull requests to be sure you’re not going to do something which is already being done by someone else.
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.
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 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:
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.
Also, don’t forget to subscribe to the blog newsletter to get notified of future posts.
