These are the CoLab's documents for how we handle version control, branch strategies, and code merges.

• Version Control: Git
• Source Hosting: GitHub
• Git Strategy: Git Flow
• Merging Code: Pull Requests
• Questions

We currently use Git for version control in the CoLab.

If you're unfamiliar with Git, it is an extremely useful tool, and one that we use daily. You'll need to familiarie yourself with the basics in order to work with, and contribute to, CoLab engineering projects.

• Overall Introductions:

  • Great overall explanation
  • In-browser interactive tutorial (from GitHub)
  • Git's official 'get started' docs (surprisingly good!)

• Relevant Specific Deeper Dives:

  • Remotes
  • Remote Branches

We host all CoLab repos under the CoLab organization on GitHub.

We use our own version of the Git Flow strategy for handling branches and releases. We follow this strictly to avoid odd bugs and unknown state in our production code.

The Git Flow development model is inspired by existing models that have been proven under various conditions.

The CoLab origin's central repo holds two main branches with an infinite lifetime: origin/master and origin/develop.

We consider master to be the main branch where the source code of HEAD always reflects a production-ready state.

Changes to master should always come through a pull request.

We consider develop to be the main branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release. Some would call this the “integration branch”. This is the branch from which all feature and hotfix branches are forked, and into which all feature and hotfix branches are merged.

Changes to develop should always come through a pull request.

• Naming convention: develop
• Branches from: master
• Must merge back into: master

Feature branches are used to develop new features for some upcoming release. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment). Basically, all feature branches are eventually pruned.

Feature branches should not exist in origin for very long. They should be merged into develop, via pull request, as quickly as possible and then cleaned up.

• Naming convention: feature-*
• Branches from: develop
• Must merge back into: develop

Here's an example of creating a new feature-headerbar branch that tracks the branch origin/develop:

> git checkout -b feature-headerbar origin/develop
Switched to a new branch "feature-headerbar"

Push your feature branch (feature-headerbar) up to Github.

> git push origin feature-headerbar

Then open a pull request on GitHub, attempting to merge your feature branch into develop. Note: Feature branches always merge into develop.

Once successfully merged into develop, you can safely delete the feature branch on GitHub as well as from your local branches.

> git branch -D feature-headerbar
Deleted branch feature-headerbar (was 05e9557).

Hotfix branches arise from the necessity to act immediately upon an undesired state of a live production version. When a critical bug in a production version must be resolved immediately, a hotfix branch must be branched from the current master.

• Naming convention: hotfix-*
• Branches from: master
• Must merge back into: first master, then develop immediately after (to ensure consistency)

Here's an example of creating a new hotfix-button_bug branch that tracks the branch origin/master:

> git checkout -b hotfix-button_bug origin/master
Switched to a new branch "hotfix-button_bug"

Push your feature branch (hotfix-button_bug) up to Github.

> git push origin hotfix-button_bug

Then open a pull request on GitHub, attempting to merge your hotfix branch (hotfix-button_bug) into master.

Once your pull request is accepted into master, immediately open up a new pull request to merge it into develop to keep things in sync.

Once successfully merged into both master and develop, you can safely delete your hotfix-button_bug branch on GitHub as well as from your local branches.

All merges from feature and hotfix branches into the develop and master branches need to be made through pull requests. Doing this accomplishes several important goals:

• Information dissemination across a larger swath of the team.
• Increased familiarity with the expanding codebase.
• Ensuring code quality / consistency.

For these reasons we ask that all merges be made by opening a new pull request and tagging someone for review. Thanks in advance!

If you have questions about any of the above, please reach out to Reid or Gavin in the CoLab.