Version control best practices

When contributing to longboxed it is good to know the proper way in which to manage commits and branches. This document attempts to describe an easy version control workflow that allows for easy branching and merging.

Longboxed developers should follow the 'git-flow' version control workflow described by Vincent Driessen on his blog:

• A successful Git branching model
• Git-flow workflow screencast

The links are provided for reference, however we will cover the main ideas below.

Two Main Branches

Git-flow's development model holds that each projects repository has two main branches:

• master
• develop

The master branch contains source code that is always in a production-ready state. The developer should never edit or commit code in this branch directly. Contributing developers should avoid entering the master branch at all costs unless they understand what they are doing.

The develop branch contains source code that reflects features and bug fixes (changes) that will eventually be merged into the production-ready master branch. develop will only be merged into master when it reaches a stable state. Developers are permitted to make small changes directly on the develop branch.

Support Branches

To ease tracking of features and assist in the parallel development between team members we use various supporting branches.

Feature Branches

• May branch off: develop
• Must merge back into: develop
• Naming Convention: feature/cool_new_feature

Creating a feature branch:

$ git checkout -b feature/cool_new_feature develop

Feature branches are used to develop new features or to fix outstanding bugs in the develop branch. When the feature/bugfix is completed it will be merged back into the develop branch and deleted.

Finishing a feature branch:

1. Switch to develop branch: $ git checkout develop`
2. Merge in feature: $ git merge --no-ff feature/cool_new_feature
3. Delete feature branch: $ git branch -d feature/cool_new_feature
4. Push develop branch to remote: $ git push origin develop

Example

Clone into the project:

$ git clone https://github.com/timbueno/longboxed.git

Checkout develop branch:

$ git fetch origin

$ git checkout -b develop origin/develop

Begin working on new feature:

$ git checkout -b feature/cool_new_feature develop

Finish working on feature:

1. Switch to develop branch: $ git checkout develop
2. Merge in feature: $ git merge --no-ff feature/cool_new_feature
3. Delete feature branch: $ git branch -d feature/cool_new_feature
4. Push develop branch to remote: $ git push origin develop

git-flow command line program

All of the above and more can be accomplished more quickly and easily with the git-flow command line program created by Vincent Driessen himself. The git-flow project repository is here.

Basics are listed below but Jeff Kreeftmeijer's blog post describes using git flow quite well:

http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/

git-flow basics

You can install it with: $ brew install git-flow

You must initialize your git repository with git-flow before you use it: $ git flow init -d

Begin working on a feature: git flow feature start cool_new_feature

Finish working on a feature: git flow feature finish cool_new_feature