GitHub PR Reviews for VIP Go sites

Overview #

This code review workflow uses GitHub’s pull request (PR) functionality, and the associated approval workflow for PRs that GitHub provide.

↑ Top ↑

How things used to work #

To deploy changes, you push up your changes to the master branch. The VIP team reviews the changes. If there are issues that need to be addressed, we create a ticket via our ticketing system, discuss the feedback, and wait for your fixes to be pushed up. Once everything looks good, we push the big, red button to deploy.

↑ Top ↑

How the new process works #

Instead of pushing directly to the master branch, we’re moving to a GitHub-flow based model. GitHub has an excellent page on what Github-flow is and how it works: https://guides.github.com/introduction/flow/

When you start developing a bug fix or a new feature, you will switch locally to a new branch. You will make changes, commit, and occasionally push up the branch. When complete and ready for VIP review, you will create a Pull Request.

The Pull Request will surface as a new review request in our internal review queue. The VIP Team will then review the PR directly on GitHub, and suggest any changes by leaving comments. Your team will go through and make any necessary changes, and when ready for another round of review, “dismiss” the review. This process will continue until the code is ready to deploy at which point the VIP Team will “approve” the request. All the communication for these status changes will flow through your GitHub repo.

At this point, the PR is accepted and control is turned over to you to merge into master. The merge triggers an automatic deploy to your production site.

If there are any issues with the deployment, GitHub provides an easy one-click way to create a “revert” for PRs (https://help.github.com/articles/reverting-a-pull-request/).

Your team can also utilise the GitHub approvals workflow, GitHub will allow any number of approvals against a PR. Please note, however, that GitHub will allow you to merge your PR to master once the PR has any approval from either the client or VIP team; please wait for approval from a VIP Reviewer before merging the PR to master.

Summary of the new flow #

  1. Create a local branch.
  2. Commit, test, push.
  3. When ready for review, create Pull Request (which initiates a review request).
  4. VIP Team reviews Pull Request.
  5. If changes are required, VIP marks Pull Request as “Request Changes”. When your changes are implemented, you “Dismiss Review” to request another review.
  6. If code is ready, VIP marks Pull Request as “Approved”.
  7. You can now merge the Pull Request to deploy.

↑ Top ↑

Why are we changing? #

GitHub’s code review tools are excellent. Among other things, they allow for inline commenting, which we feel is the best and most direct way to share feedback on code. There are other possibilities for integrations with Continuous Integration servers (like Travis and TeamCity) that we’re exploring as well that would be much easier to do via GitHub.

The updated workflow also gives you control of the deploy to the production site. Any merge to master triggers a deploy, which means that once approved, you can deploy your PR at your convenience. It also simplifies rollbacks/reverts as the Github UI provides a simple one-click method to revert PRs.

↑ Top ↑

What about non-production environments? #

Your non-production site(s) and workflow(s) remains as-is. For example, merges to the develop branch deploy automatically to the develop site without VIP involvement.

We highly recommend following GitHub-flow for non-production environments as well. An example workflow with a develop environment could look something like:

  1. Create local feature branch (add/new-feature).
  2. Develop, test, commit changes.
  3. Push up changes to new remote branch.
  4. Create a PR from the remote add/new-feature branch to develop.
  5. (Optional and recommended) Internal team code review.
  6. Merge PR and test on develop environment.
  7. If everything looks good, create a PR from the remote add/new-feature branch to master.
  8. Proceed with VIP Code Review.

↑ Top ↑

My code is approved, how do I deploy? #

Once a member of the VIP team has approved your code, the next step is to merge your code to master which triggers this code to be deployed on the site. Typically deployment takes less than ten seconds.

GitHub documentation on merging a pull request.

↑ Top ↑

Scheduled Reviews for large changesets #

Large changesets or PRs take longer to review,  and can be more complex. If the changeset is larger than about 1,000 lines of code it may need more time than our traditional review/deploy workflow facilitates, to give it the proper attention it deserves. In these cases we may mark your PR as [Status] VIP Scheduled Review, and set a date when we can assign an engineer to spend the required time to review your changes; alternatively you could break the PR up into smaller, more atomic commits, and submit a number of smaller PRs.

↑ Top ↑

Common git Scenarios #

↑ Top ↑

How do I create a Pull Request? #

GitHub has an excellent guide that covers this in detail: https://help.github.com/articles/creating-a-pull-request/

↑ Top ↑

How do I test a colleague’s PR branch on my local machine? #

You can create a local branch that “tracks” a remote branch. Find the branch name for your colleague’s PR then use the following to checkout the branch locally:

Let’s say the branch is called “add/new-feature”:

git checkout -t origin/add/new-feature

You can now test the changes in your local environment. You can also commit, push, and pull directly to/from the branch as well.

More details on tracking branches at http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html

↑ Top ↑

I merged and deployed my PR. How do I get started on my next feature? #

Congratulations on your successful merge and deploy. Take a moment to celebrate, first! 🙂

Then:

# Switch back to master
git checkout master

# Get the latest changes
git pull origin master

# create a new branch and continue development

↑ Top ↑

Oh no! I committed to the master branch! #

We can fix this.

You first need to figure out how many commits you need to move over to the new branch. Let’s say it’s 3 commits.

# Create a new branch with your commits included
git checkout -b add/feature

# Switch back to master
git checkout master

# Delete the commits from the master branch
git reset --hard HEAD~3

# Go back to your new branch
git checkout add/feature

# Continue on with your development

As another example, if it was 1 commit, your reset command would change to git reset --hard HEAD~1

↑ Top ↑

There were some updates to master and now my PR branch is out of sync. How do I update my branch to get the latest version of the site’s code? #

# Switch to master
git checkout master

# Get the latest updates
git pull origin master

# Go back to your working branch
git checkout add/new-feature

# Rebase the changes from master into your branch
git rebase master

If you run into conflicts, GitHub has excellent resources on how to resolve them from the command line:
https://help.github.com/articles/resolving-merge-conflicts-after-a-git-rebase/
https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/

If you get errors about fast-forwarded branches, you can force push to the branch to get your changes up to the remote branch.

git push --force origin add/new-feature

↑ Top ↑

Someone else pushed updates to my branch and now git is complaining when I try to push up my changes. #

# Pull the changes from the remote branch and rebase them locally
git pull --rebase origin add/new-feature

# Fix any conflicts that come up

# Force push to the remote branch
git push --force origin add/new-feature

↑ Top ↑

Git Tools & Resources #

↑ Top ↑

Guides #

↑ Top ↑

Apps #

Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.