Next Spaceship

Driving into future...

GitHub Workflow for Submitting Pull Requests

| Comments

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 git@github.com:<username>/<repo-name>.git
git clone git@github.com: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 git@github.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...

Staying updated

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.

Comments