Summary
In this post, I will show you how to contribute to projects on GitHub using a fork and pull workflow. I provide a detailed set of beginner-friendly steps that demonstrate how to fork a GitHub repository all the way through opening a pull request.
Introduction
Using a fork and pull workflow for GitHub is a great way to contribute to open source projects where there are multiple contributors and especially if you are new to making open source contributions.
Forking the repository
The first step is to set up git on your local machine - you can find instructions on how to do that here. Then, set up authentication to GitHub from git by following the instructions here.
Next, navigate to the repository on GitHub that you want to contribute to. On the top right corner of the page, click on the Fork button as shown here. Now that you have forked the original repository on GitHub, you will have a new repository listed under Repositories in your GitHub profile. Navigate to that newly created repository and click on the Clone or download button as shown here.
Next, select either the Clone with HTTPS or Use SSH option. HTTPS is the default option. For more information about each option, GitHub provides detailed information here. Next, click on the clipboard icon and that will copy the repository URL to your clipboard.
Cloning the repository for local editing
Then, in your terminal, navigate to the directory where you want to save the repository on your computer. Next, type git clone followed by a space and the repository URL that you copied to the clipboard.
git clone repository-URL
Now that you have your repository cloned, you have a local copy on your computer that you can edit with your editor of choice.
Create a new branch and make changes to the code
In order to make changes that will become a pull request, you’ll first want to create a new branch for the repository. To create a new branch, type git checkout -b followed by a space and the branch name.
git checkout -b branch-name
A standard way to name a branch is to choose a descriptive name in all lowercase letters that reflects the changes you will be making separated by a dash for each word. After you have made your changes to the code in your local repository, the next step is to use the git add . command to stage your changes for commiting to git (the period at the end isn’t a typo 🙂).
git add .
Now that your changes are staged, that is followed by the git commit command
git commit
or git commit -m with a space followed by your commit message in double quotes.
git commit -m “Your commit message goes here”
The git commit command (without using the -m flag and a commit message) allows you to write a brief summary message in your terminal editor, followed by a more detailed what and why explanation of the changes made in the commit. The default terminal editor is called Nano in macOS, which is what I’m using for this article.
Here is a very good post about how to write great commit messages: https://chris.beams.io/posts/git-commit. In Nano, in order to save your commit message, press Ctrl + X , followed by Y when prompted and then hit Enter. See here for more help with Nano: https://www.nano-editor.org/dist/v2.9/nano.html.
Set up remote repository and push your changes
Now that you have your changes committed, the next step is to push your changes to the remote repository. Since you are working with a fork, your origin branch should be your fork that is connected to your GitHub account when you clicked the Clone or download button. To view what remotes are set up, type git remote -v in your terminal.
git remote -v
You should see that your fork is listed as origin. Since you’ll want to open a pull request for the original repository that you forked, you’ll want to add that original repository as the upstream repository. To do that, first go to the original repository’s URL on GitHub and do the same thing you did above in order to get the URL that you cloned saved to your clipboard. Then, type git remote add upstream followed by a space and that copied repository URL with .git at the end of the URL.
git remote add upstream https://github.com/ORIGNAL_OWNER/ORIGINAL_REPOSITORY.git
Now that the upstream remote has been added, you’re ready to push your changes by using the git push command.
git push
Open pull request
Now that your changes have been pushed to your remote fork on GitHub, all that’s left is to open a pull request. In order to open a pull request, go to the original project repository page and you should see that your fork was pushed to GitHub and a New pull request button will be displayed: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork.
Click on that button and you’re set to open a pull request for that repository! Writing a good pull request is beyond the scope of this post, but many projects will have a contribution guide that you should read before making your first pull request.
Conclusion
I hope that this post helps you in managing your workflow if you are new to contributing to projects on GitHub or as a helpful reference. Check out the great resources below for more information about the topics described above. Happy coding!
Resources
- Thanks to Ali Spittel for her blog post that I found especially helpful in writing this article. Check out her website.
- GitHub help article on working with forks
- Git documentation
- How to write a git commit message
- Creating a pull request from a fork
Top comments (0)