This document is for internal reference and is intented only for primary developers on the MobileTribunal project. This workflow is based on http://nvie.com/posts/a-successful-git-branching-model/ and this document will only serve to provide a paraphrased set of guidelines found there.

Basics

We have three primary branches: master, production, and develop. The master branch is only updated to stable releases. The develop branch is pushed out to the beta server on a regular basis. When a stable release has been reached, develop will be merged into master and tagged with the new version number. The production branch is the same as the master branch except with a few additions specific to the case of running the primary public host (including analytics code). The default distribution offered to visitors will be the latest from the master branch.

Standard Workflow

Although our other hosts serve as git remotes, the one on github shall be the authoritative remote for sharing commits. Push to github before anywhere else, and fetch updates from github rather than the server remotes.

The process a new commit will take to make it to the production host is as follows:

• Edits are made and committed to the develop branch
• The develop branch is pushed to github and the test host
• When confirmed as a stable release, merge develop into master and tag with new version number
• Merge master into production and push production to the public host
• Push master and production to github

Details on each step of this process is described below.

Remote names

In the interest of always knowing where I am pushing, I don't maintain a remote named "origin". Instead each is explicitly named (i.e. github, phpfog, heroku). If you just cloned this repository from github you can easily rename your remote:

$ git remote rename origin github

Sharing changes to the develop branch

Make sure you're up to date, then just a simple push.

$ git pull --rebase github
$ git push github develop

Deploying the develop branch

Because our hosts serve only what they have on the master branch, the develop branch must be pushed as an update to the remote's master branch.

(you will need to be a bit more verbose)
$ git push phpfog develop:master

Preparing a release (merging develop into master)

When the develop branch has reached a stable point and is ready for a new release, it should be merged into the master branch and tagged with the new version.

$ git checkout master
$ git pull --rebase github
(always make sure you are up to date)
$ git merge --no-ff develop
$ git tag -a 1.1
(git will ask for a tag message, use "Version 1.1", release notes may follow after a blank line)
$ git push github master
$ git push --tags github

Deploying a release to our public host

Deploying a new version to the public host requires adding the new changes to the production branch, and then pushing it to the master branch on the public host. In this case, the default fast-forward behavior is acceptable, since the history of the production branch isn't worth saving. (It's the same as the master branch with a few extra commits floating in front.)

$ git checkout production
$ git pull --rebase github
$ git merge master
(merge conflicts may need to be dealt with; then push to heroku or another public host)
$ git push heroku production:master
$ git push github production

Feature branches

When developing a significant feature, it may be prudent to isolate those changes to their own branch. The following demonstrates that workflow.

$ git checkout -b shiny_new_look develop
(run normal development workflow on this branch)
(then when finished)
$ git checkout develop
$ git merge --no-ff shiny_new_look
(resolve any merge conflicts)
$ git branch -d shiny_new_look
$ git push github develop