GitHub Pull Request

From Dogtag
Revision as of 18:45, 19 September 2018 by Mharmsen (talk | contribs) (GitHub - Merge and update fork)

Jump to: navigation, search

Overview

Github Pull Request is a way to keep the official repo clean by allowing other developers to review your patch(es) before it gets merged into the corresponding branch. It offers a lot of benefits over the gerrithub. See Gerrit vs GitHub Pull Request for entire adv/disadvantages

GitHub - Initial setup of a remote forked repo

  • Create a fork of the upstream project by clicking on the fork button:

Gh pr fork.png

  • Now, you'll have your own copy of a remote forked repo in the format: https://github.com/<your Github ID>/pki.

Local Repo - Initial setup

  • Clone the upstream project into a local repository:
$ git clone https://github.com/dogtagpki/pki.git 
  • Add the remote forked repo to your local repo:
$ cd pki

# If you want to type in Github username/pass for every push
$ git remote add personal https://github.com/<your Github ID>/pki

# OR

# If you want to use an SSH authentication using your synced key-pair
# Note: This doesn't prompt for Username/password for pushing the changes
$ git remote add personal git@github.com:<your Github ID>/pki.git

If you want to set up SSH keys for github account, please follow this guide

  • Check whether you see the following output:
$ git remote -v
origin	https://github.com/dogtagpki/pki (fetch)
origin	https://github.com/dogtagpki/pki (push)
personal	https://github.com/SilleBille/pki.git (fetch)
personal	https://github.com/SilleBille/pki.git (push)

Travis - Enabling Travis CI for the remote forked repo

1. Go to https://travis-ci.org/ and sign in using Github (Top right button).

2. Add the remote forked repository by clicking the + sign next to My Repositories.

Travis 2.png

3. Select the remote forked repository.

Travis 4.png

If necessary, click on Sync projects from GitHub or Sync account on the top right of the page to refresh the list of repositories.

GitHub - Verifying Travis CI for the remote forked repo

  • Go to https://github.com/<your Github ID>/pki/settings/installations, or in your remote forked project, go to Settings -> Integration & services, verify that Travis CI appears under Services.

Travis 5.png

Local Repo - Submitting patches from a local dev branch

  • Within your local repo, checkout the branch to which you want to submit one or more patches:
# To submit patches to master:
$ git checkout master

# To submit patches to DOGTAG_10_5_BRANCH:
$ git checkout DOGTAG_10_5_BRANCH
  • Create a new local dev branch (which you'll be submitting as the PR):
$ git checkout -b ticket-<number>
  • Make changes (or cherry-pick changes from other branches) and commit them to your local dev branch:
$ git commit -a
  • Optionally verify that the commit(s) have been committed to the local dev branch:
 # For master:
 $ git branch
   master
 * ticket-<number>
 
 # For DOGTAG_10_5_BRANCH:
 $ git branch
   DOGTAG_10_5_BRANCH
   master
 * ticket-<number>
  
 $ git log
  • Push the local dev branch to your remote forked repo:
# Note that ticket-<number> is the new local dev branch you created
$ git push personal ticket-<number> 
  • This will trigger a travis CI build against your forked repo.

Travis - Verifying results of the Travis CI build

GitHub - Creating a Pull Request

  • Submit a pull request from your branch:

Gh pr newPR.png

  • Choose the correct to and from branch. You should see the list of commits that will form a patch. You'll see a screen similar to this:

Gh pr correct.png

If there is an error, you'll see something like this:

Gh pr incorrect.png

  • Fill in the Commit Message and Commit Description that will eventually appear in the official upstream repo commit history.
  • Add the reviewers (Github provides reviewer suggestions based on the history of the file)
  • Click on "Create Pull Request".

GitHub - Merge and update fork

  • Once your patches go through and changes are reviewed, your patches are ready to be merged.
  • Click on the drop down next to "Merge":

Gh pr merge.png

 IMPORTANT:  Use the DROP DOWN as just pressing the "Merge pull request" button will default to the undesirable "Create Merge Commit" option!

  • Use the following guideline to keep the official repo commit history CLEAN:
Create Merge Commit = Creates a new commit on top of the last commit in the official branch (Not recommended)
Squash & Merge      = Use when you have lot of insignificant commits (like correcting changes from reviewers). This will Squash all your commits into 1 single commit
Rebase & Merge      = Use when your patch is actually a combination of different patches (every commit is significant). This will copy ALL the commits on top of the last commit in the branch
  • Once merged, Github will provide you an option to delete your branch. DELETE IT!
  • Now, to keep your fork clean and in-sync with official repo do this in your local repository:
$ git checkout master           # or the branch you want to sync
$ git pull origin master        # or the branch you want to sync
$ git push personal master      # or the branch you want to sync
$ git branch -D ticket-<number> # Delete the local branch which you deleted from Github

References