This post serves as a simple walk-through of how to contribute to a repository or collaborate on a project with others using github.com. The content is broken down into three sections:
(1) How to create your own fork of the repository that you wish to contribute to.
(2) How to sync your branch with a branch from your upstream repository (the upstream repository is the repository you created your fork from).
(3) How to submit your new code as a pull request to the upstream repository. If you have already created a fork of the repository and have cloned your fork to your dev box you can skip to the second section.
(1) Creating your own fork: Whatever project you are going to contribute to, you will want to create your own fork of the repository, or “repo.”
Browse to github.com and navigate to the repo you wish to work on. Once there, in the top right hand corner click “Fork”.
Once you have created your fork you now have your own repo of the code to edit as you see fit. After you make changes you can make pull requests back to the original repo. Next you will need to get all that lovely code on your development box and get it all set up up to work collaboratively.
You will need to get the link to git clone your repo. On github.com navigate to your repository that you just forked: https://github.com/<yourusername>/<reponame>
On the repository page select if you want to clone via HTTPS or SSH (for SSH you must have your certificate setup, for which github provides a guide).
Next, on your development box you will need to clone down the repo. This will bring that repo’s master branch on to your local dev computer! This will all be done via the command line from your terminal (Mac or Linux) or git command prompt for Windows:
git clone <clone link you got above>
Now that you have the repository on your dev box, change your directory into the repo that you just cloned down:
cd <cloned repo>
Now we need to setup up remotes. The main one you need is the repository that you forked from. Generally this is known as the “upstream” repository. To do this you will need go back to the repository that you forked and grab the clone link for it. With the clone link do the the following command:
git remote add upstream <clone link from the original repo>
(2) Syncing your branch with the upstream repository: To verify that you have added the remote correctly run the following command:
git remote -v
This will display all remotes you currently have for this local repository. If you do not have your upstream set up, please revisit the last part of the first section.
If you just created your fork, you will not need to sync your fork with the upstream repo, but if it has been awhile since you forked, below are the steps to sync your master branch with the upstream master branch. Also, if you are working in a different branch from upstream such as a dev branch, you will need to do this step, just replace “master” with the appropriate branch name.
Now before you start making the changes to the repo that you want to, it’s always best to get the latest code from the upstream repo. This is known as “syncing forks.” Once that is completed you will want to create a topic branch.
First, you will fetch from the upstream. This will get the delta between your repo and the upstream repo:
git fetch upstream
Next, you will want to check out your local master branch, or the branch you are syncing to the upstream repo:
git checkout master
Following that, merge in the new changes from the upstream branch:
git merge upstream/master
With merge you will not loose any local changes you have made. Generally my suggestion is never make changes to your repo master branch, always use it as a sync for upstream. It will make everything easier in the long run. Utilizing topic branches (which I will describe in a moment) will help keep all the code cleaner and easier to manage in a collaborative environment.
If there were no issues with the merge it should have just fast-forwarded. You will have to work through the files that are having merge issues and decide what you want/don’t want to keep. This is the reason I don’t recommend making changes in the master branch on your personal repo.
Next we will push the merge result to our local master and finalize the syncing of your repo with the upstream:
git push origin master
Now it’s time to create a topic branch in our repository and start making changes to the code! A topic branch is a branch you will create in your local repository to which you are making changes that will be submitted to the upstream repository. These topic branches should have simple names (for example, “fix-missing-pkg”) for you to identify what changes you are working on so you can go back and make changes as required based on feedback from your pull request. Also, these topic branches must remain open until your pull request is approved. Therefore, having multiple topic branches helps to keep all changes separate and allow you to work on other changes while you wait for the pull request to be approved. To create the branch run the following command:
git checkout -b <name_of_the_new_branch>
(3) Submitting your code as a pull request: At this time you can make changes to the code on your dev box as you see fit. Once you are happy with the results you can push it into your fork’s topic branch. To view all the awesome changes you have made the following commands are very useful:
git status
git diff
When you are ready to commit your changes you will need to identify what files you want to push up.
Generally a “git status” is useful to identify what files you made changes to.
git add <name of files>
Now we need to add a comment to the commit we are going to make. Make it meaningful so you know what changes where made.
git commit -m "I made awesome changes"
Now push the code up to your local topic branch.
git push origin <name_of_the_topic_branch>
To create the pull request to the upstream repository go to github.com and log in to view your repository. Right above the code, where you select the branch you want to view on the website, click “New pull request”.
You need to tell GitHub what branch you want the code to go to, and what branch it is from. This is the Base fork and the Head fork, respectively. I think of the Base fork and branch as where my code is going, and Head fork and branch is my repository and topic branch. Review the differences between the branches, and if you are satisfied click “Create Pull Request.”
Put in comments for the changes you made, how it works, and what tests should be preformed to verify the code is working correctly. Then click “Create Pull Request”. It is usually best to do @<githubuser>, where <githubuser> is the person you want to review the pull request. This alerts them that you have made a new.
The pull request will then be reviewed and tested prior to the merge being completed. The reviewer will generally make comments on your code if there is any thing that needs to be addressed.
If they request you make a change, do so in the local topic branch and then just push it back up to your origin topic branch, and it will automatically update the pull request.
For more git commands here are a couple of git cheat sheets:
https://github.com/arslanbilal/git-cheat-sheet
https://help.github.com/
Go fourth and contribute to open source projects! GitHub makes it simple and easy.
