Why Contribute to GitHub?
GitHub is an online repository hosting service where you can host your own projects, and contribute to projects created by other people.
There’s many reasons why you might decide to contribute to one of the many open source projects hosted on GitHub. Maybe you’re a fan of the project in question, or just open source in general, and want to give something back to the community; maybe a project contains a bug that you know how to fix; or maybe you’ve come up with an idea for a great new feature, and want to share it with others.
Whatever your motivation, this tutorial contains everything you need to know, to start contributing to your favourite GitHub project.
What You’ll Learn
Over the course of this tutorial, you’ll learn how to ‘fork’ the repository that contains your chosen project. When you fork a project, you create a GitHub-hosted copy of the original repository; however, since this copy only exists on GitHub, you can’t work on it directly. To get around this problem, you’ll learn how to create a local clone of your fork. You can then make whatever changes you want to this local clone, from the comfort of your own computer.
Once you’ve finished working on your clone, you’ll bundle all your changes into a commit, and then push this commit to your fork. Finally, you’ll ask the project’s owner to apply your changes to their original project, by sending them a pull request. If your pull request is accepted, then your changes become part of the project.
Making Your First Pull Request
The following steps show you how to make your first contribution to a GitHub-hosted project, using GitHub’s demonstration repository, “Spoon-Knife,” as an example.
Note, this tutorial requires a GitHub account, and for you have to have installed Git. When you communicate with Git, you enter all commands into the Terminal (if you’re a Mac user), or the Command Prompt window (if you’re a Windows user).
1. Fork and Clone the Original Repository
Navigate to the repository of the project you want to contribute to. For the purposes of this tutorial, this is the Spoon-Knife repository:
Fork the Spoon-Knife repository, by clicking the ‘Fork’ button in the upper-right corner of the screen.
Click the Fork Button
Remember that this fork exists on GitHub only. Before you can make any changes to this project, you need to copy its files and folders from your GitHub-hosted fork, and onto your computer.
Open your Terminal/Command Prompt, and enter the ‘git clone’ command, followed by the URL of your fork. GitHub creates a clone of your fork, and stores this clone in its own folder on your computer.
2. Connect Your Clone to the Original Repository
Before making any changes to your project, you should take the time to configure Git so that it can pull any changes that occur in the original repository, into your local clone. This allows you to incorporate changes that are happening in the original repository, into your own work.
To connect your clone to the original, or ‘upstream,’ repository, you need to tell your local clone where it can find the original repository. Run the ‘git remote add upstream’ command, followed by the original repository’s URL (not the URL of your fork).
In our Spoon-Knife example, the command is:
git remote add upstream https://github.com/octocat/Spoon-Knife.git
If at some point you want to check that your clone is connected to the correct upstream repository, run the ‘git remote -v’ command, and check which URLs are displayed. The ‘original’ URL should point towards your fork, while the ‘upstream’ URL should point to the original repository.
3. Make Your Changes
You can now start working on your local clone. While you’re making your changes, it’s a good idea to frequently check for updates to the original repository. If Git finds any changes, it automatically pulls them into your local clone.
To check for changes, run the following command:
git fetch upstream
Although Git automatically pulls any changes into your local clone, it doesn’t merge these changes with your current branch. Instead, it stores the changes in a new local branch, called “upstream/master.” If you do want to update your current branch with the changes in upstream/master, you need to perform a merge:
git merge upstream/master
4. Create Your Commit
Once you’re happy with the changes you’ve made to your local clone, the next step is sending these changes to GitHub.
Start by telling Git which changes it should include in its next commit, by running the ‘git add’ command, followed by the name of the file containing your changes. This may be a file you’ve updated, or a new file you’ve created. For example, if you created a file called CODE that you want to commit, you’d run the following:
git add CODE
When you ‘git add’ a file, you’re telling Git to add it to a staging area. All your changes need to be staged before Git can ship them to GitHub, so keep running ‘git add’ until you’ve added all your updated/new files to the staging area.
When you’re staging your files ready to commit to GitHub, at some point you may want a reminder of exactly which files you’ve added to the staging area. To see a list of all the files that are currently staged, run the following command:
Once you’ve staged all your changes, you need to create your commit, and provide a log message describing your changes. It’s particularly important that you provide a log message for every commit, because if you ever need to inspect your project’s history, past log messages can be an invaluable source of information.
To create your commit, run ‘git commit,’ followed by your log message:
git commit -m "Created a new CODE file.”
5. Submit a Pull Request
It’s time to push your commit from your local repository, to the fork you created on GitHub, by running the following command:
The final step is making your pull request. Log into your GitHub account, and navigate to the original repository.
Open the ‘Branch’ dropdown menu, and select the branch that contains your recent commit. Then, click the green ‘Compare and Review’ button.
Compare and Review
Click the green ‘Create Pull Request’ button, and write a short description of the changes included in this commit. Finally, click ‘Create pull request.’
Congratulations, you’ve just made your first pull request! Now all you can do is wait, and see whether your work is accepted into the project.
In this article, you learned how to fork, clone, commit, push, and make a pull request. This is everything you need to know, to continue making contributions to the various open source projects on GitHub.
If this article has inspired you to create your very own, GitHub-hosted project, you can find out how to create your own repository, and start committing files, by checking out our Creating Your First GitHub Project article.