How to contribute to an open-source repository on GitHub
On GitHub, you can submit changes to a public repository with three main steps:
- Fork the repository.
- Commit your changes.
- Submit a pull request.
This post walks you through each step.
Before you start, you need Git installed and an account on GitHub. You should also read the project’s README or CONTRIBUTING files to see if they give any guidelines for submitting pull requests.
Fork the repository
Sign in to GitHub, and go to the repository that you’d like to contribute to. The URL will look like
https://github.com/owners-username/repository-name
In the top-right corner, click “Fork.”
GitHub will bring you to your fork. The URL will look like
https://github.com/your-username/repository-name
Clone your fork
To clone your fork, first copy the fork’s URL.
Then, in your terminal, enter this command, replacing the URL below by pasting the fork’s URL.
$ git clone https://github.com/your-username/repository-name.git
This clone command creates a local copy of the repository on your machine. Before entering any more Git commands, cd into the repository.
$ cd repository-name
Add an upstream remote
You should periodically bring your fork up-to-date by fetching changes that have occurred in the original repository. In this case, the original repository is called the upstream repository. Before you fetch upstream changes in your fork, you’ll need to add the upstream repository as a remote.
Go to the original repository’s page.
https://github.com/owners-username/repository-name
Copy the original repository’s URL.
In your terminal, enter this command, replacing the URL below by pasting the original repository’s URL.
$ git remote add upstream https://github.com/owners-username/repository-name.git
To check if this worked, enter this command.
$ git remote -v
The output should look like this.
origin https://github.com/your-username/repository-name.git (fetch)
origin https://github.com/your-username/repository-name.git (push)
upstream https://github.com/owners-username/repository-name.git (fetch)
upstream https://github.com/owners-username/repository-name.git (push)
Bring your fork up-to-date
You can now bring your fork up-to-date with changes that occur in the original (upstream) repository.
In your fork, fetch changes from the original repository with this command.
$ git fetch upstream
Check out your master branch.
$ git checkout master
To bring your fork’s master branch up-to-date with the original repository’s, use this command to merge the history of the upstream repository’s master branch into your fork’s master branch.
$ git merge upstream/master
To bring a different branch up-to-date with the upstream repository, simply replace master in the two commands above with the name of the branch you’d like to sync.
Having configured your fork, you’re ready to code.
Commit your changes
While you have your master branch checked out (or whichever branch you synced above), check out a new branch to work on a particular change.
$ git checkout -b readme_update
Do your work, and add your changes to the index. You can add all of the files that you’ve changed or created…
$ git add -A
…or you can add only specific files.
$ git add README.md
Commit your changes on this new branch.
$ git commit -m "Update README file"
If the upstream branch you’re working off of has changed since you checked out your new branch, you have the option to rebase your new branch off of the upstream branch. This step will give you the opportunity to resolve merge conflicts locally before you submit a pull request.
$ git pull --rebase upstream master
If you’re working off of an upstream branch other than master, simply use the upstream branch’s name in place of master above.
Having finished your work, you’re ready to submit these changes to the original (upstream) repository.
Submit a pull request
In your fork, push your branch to your origin remote.
$ git push origin readme_update
Go to the original repository’s page.
https://github.com/owners-username/repository-name
Click “Pull Requests.”
Click “New pull request.”
Since you pushed your branch to your fork’s origin remote, you need to click “compare across forks” to select your branch.
Set the “base fork” to the original (upstream) repository, and set the “base branch” to master (or whichever branch you synced with earlier). Set the “head fork” to your fork, and set the “compare branch” to whichever branch you pushed up earlier (in this example, it’s readme_update).
Click “Create pull request.”
In the comment box, explain the reason for your pull request, and describe what your code does.
To submit your pull request, click “Create pull request” a final time.
A shortcut
After pushing up your branch, GitHub may show you an option like the one below—either on the original repository’s page or on your fork’s page.
As a shortcut, you can click “Compare & pull request.” Then follow the rest of the steps described above to submit your pull request.
⁂
Subscribe to my mailing list if you’d like to read more.