RemoteFlow Branching Model For Continuous Deployment

We’ve used multiple other branching models with some success, including the Gitflow branching model but there is a better way for remote teams who want to deploy continuously. We call this the Remote Integration Branching Model or RemoteFlow for short.

If your release has ever been delayed because the master branch had broken code, then you’re going to want to keep reading. Or if you’ve ever got yourself into rebasing hell trying to back out changes that were merged but no longer needed, you’re about to be set free.

In its simplest form, we branch features off master, integrate and test them on develop, and then merges them back into master. Below we’ve included some important rules and tips, but don’t let that fool you into thinking this is complicated.

Benefits of the continuous deployment branching model:

• Allow all features from multiple team members to work their way to production simultaneously and continuously as they’re completed
• Minimize the possibility of a feature becoming a blocker for other team members, features, or releases
• Prevent unproven code from ever accidentally or maliciously getting to the production server and from being unknowingly propagated to other features
• Allow multiple features to be tested on a QA server (or staging server) at the same time while allowing for any changes found to be corrupt to be wiped from all environments quickly
• Give team leaders more visibility and control over how and when changes move to production
• Improve the clarity of merge conflict resolutions and decrease the likelihood of code code loss
• Make it easier to start, stop, and re-start new features.

Two Deadly Serious Rules

Ok, they’re not deadly except to team mojo, but here are two rules that you should never forget:

1. Never merge the develop, qa, or staging branch into any other branch, these branches are always assumed to be corrupt because they’re used to test all features that can become corrupt.
2. Always branch new features off the master branch (e.g. git checkout -b INSERT_FEATURE_BRANCH_NAME) and keep them up to date by merging in master often.

Prerequisites

1. Make sure you have Git installed on your terminal.
2. Clone your code locally (e.g. git clone [email protected]:vuejs/vue.git .).
3. Start with a master branch and create a develop branch off master.
4. Create a feature branch off master and start coding.

Branching Summary

Let’s dig into a little more complete summary of the model. First, branch your feature off of master, make your code changes on your feature branch, and then create a pull request into develop. Now you’re ready to send a pull request to your lead developer for a code and user review. Once the quality of your feature is assured, we merge it with master and deploy it to the production server. Notice we do quality assurance before you merge it to master, this is key.

The develop branch is used to test changes on a QA server and can be corrupted and/or thrown away at any time (hence one of the deadly rules above).

You may be thinking this model will increase merge conflict problems but the exact opposite is true, it just changes the timing of resolving conflicts and gives you more control. We’ll talk about this more below, but the main thing to remember is that you’re conflicting with another feature branch, not develop.

Branching Steps

At this point, you could probably figure the rest out on your own, but we’re going to list out our full internal process because it it is filled with tips and tricks to help you manage the code of an entire remote team easily and effectively.

Let’s imagine you’ve been assigned issue #999, a bug squashing change requested by a stakeholder.

1. You’ll need a new branch to keep all your changes together, we call this a feature branch.
2. Always branch features off the master branch (e.g. git checkout master; git checkout -b 999-bug-squish;).
   • Note the issue number prefix (e.g. 999) on the branch name helps connects your feature branch to the change request.
   • In a perfect world, each issue should have only one branch to make it easy to move your changes through testing to production. We note this branch name at the issue link so it doesn’t get lost.
3. Make your changes on your feature branch and commit them.
   • Pro tip: draw a clear connection between your changes and the issue that requested them by including the issue number in the commit message (e.g. git commit -m '#999 squashed some bugs'). Your team will love you for this.
   • Pro tip: before committing, run git diff to make sure you’re not committing unnecessary changes.
4. Merge master back into your feature often to make sure it is up-to-date (e.g. git checkout 999-bug-squish; git pull origin master;).
5. Push your changes back to the origin (e.g. git push origin 999-bug-squish).
6. Create a pull request (PR) into develop
   • Remember, only proven code makes it to master and it must be proven on develop. We call this the integration branch and it can easily become corrupted by a developer mistake.
   • Pro tip: if your changes affect what the user sees (i.e. the view), include a GIF of the new view to make it easier for the reviewer to review. We recommend attaching the GIF to the PR because that is where questions will arise.
7. If your pull request has a conflict, don’t break one of the deadly rules…
   • Remember, your conflict is not with develop, but with another feature merged into develop ahead of yours. The following diagram may be helpful you visualize how to resolve conflicts.

     

   • Pro tip: first, try merging in the latest from master. The conflicting feature may already be merged into master and syncing your branch could save you a lot of time.
   • If merging in master doesn’t help…
     • Find the third party branch that conflicts with yours and reach out to your lead developer to make a decision whether you should make your code dependent on that branch.
     • Pro tip: find the conflicting branch by using the Blame/Annotate feature of Github/Bitbucket. This is where good commit messages from step #3 can come in handy.
     • Pro tip: if you do make your branch dependent on another feature branch by merging it into yours, note this dependency on the original issue link for #999.
   • IMPORTANT: the most common mistake when resolving a merge conflict is to delete another developer’s code. You need to be thoughtful about why the conflicting changes were made and double check with the other developer before deleting anything.
8. One last thing before you submit your pull request for review, do a mock review yourself.
   • Both Github & Bitbucket provide the ability to review and comment on your pull requests. Make sure all your changes are needed and wanted, use comments to explain unusual looking code, make any last minute re-factoring.
9. Submit for review by comment on the original issue #999 and include a link to the pull request
   • Pro tip: if the changes require special “steps to go live” or counter intuitive “steps to test”, make sure to include those as well when you submit for review.
10. Your feature branch’s code changes are then reviewed, merged into develop, and deployed to the QA server for further testing by the customer.
11. Once approved to production, your branch is merged into master and deployed to the production server.
    • This is why you should note your branch name on the issue link, so code changes don’t get missed.
12. Whenever master changes, you’ll need to merge it back into develop to keep develop up-to-date
    • If master ever has a conflict with develop delete the develop branch and create it again as a copy of master