The original source of this document is from OpenShift.
This document describes the recommended workflow to maintain a fork of a GitHub repository and how to submit pull requests for new features or bug fixes. The examples used on this page can be used for any GitHub repository.
Forking a repository
Before you can begin editing code you must first create a fork of the GitHub repository you wish to contribute to.
Navigate to the GitHub page of the repository you wish to fork. Click on the fork button on the top right corner of the page.
This creates a copy of the repository in your own GitHub space.
Cloning your fork
Clone the repository from your fork
git clone email@example.com:<username>/<repo-name>.git git clone firstname.lastname@example.org:kraman/crankcase.git
Add the upstream repo so that you can pull changes
git remote add upstream <original repo git url> git remote add upstream email@example.com:openshift/crankcase.git
Working on a topic branch
Always try to avoid working on the master branch. It usually results in merge conflicts and/or update issues. Instead, work on a bug/feature/topic branch whenever possible.
#start from the master branch git checkout master #create a new branch git branch dev/kraman/bug/12345
#switch to the new branch git checkout dev/kraman/bug/12345 #...make changes...
Once a fork has been created, it does not automatically track the upstream repository. Follow the steps outlined below to keep the master branch up-to-date.
#pull the latest changes from upstream git fetch upstream git fetch upstream --tags
#make sure there are no un-committed changes git stash
#make sure we are working on the master branch git checkout master
#merge the latest changes git merge upstream/master
#push the updates changes to our GitHub fork git push origin master git push origin --tags
#return to your bug/feature branch git checkout dev/kraman/bug/12345
#rebase this branch onto latest code from master (expect conflicts) git rebase master
#... resolve conflicts
#push the rebased branch back to your fork git push origin dev/kraman/bug/12345 -f
#Restore any un-committed changes git stash pop
NOTE: The git stash steps are optional. It is easier if you commit all changes before attempting a rebase.
Submitting a patch
Once your code is ready to be submitted, you will need to submit a pull request with your changes.
- Update your branch and make sure you are rebased off the latest upstream/master
- Squash your commits onto a single revision
- Submit a pull request on GitHub
Squashing your changes into one revision
Before you can submit a request, rebase all your changes on to a single commit. This makes it easier to review and also makes reverting the code easier in case of any build breakages.
git rebase -i master #... squash commits ...
Creating a pull request
GitHub instructions on creating a pull request
If you need to make changes to your commit after a pull request has been issues, you can go back to the pull request page and update the commit range rather than submit a new pull requests.