#summary Releasing Melange
#labels Importance-Featured,Phase-Deploy,Contents-Complete,Featured

<wiki:toc max_depth="2" />

= Release Timing =

Melange releases on an irregular basis as bug fixes and new features become available. More than one release per day is an indicator that some urgent issue is being addressed, more than ten days since the last release is an indicator that something is blocking new releases from being made, and one to two releases per week is considered average and healthy.

= How to cut a release =

* Releases are _always_ made from Melange's master branch at a commit at which all tests pass. *

== Selecting a version identifier ==

Melange releases are identified by strings of the form "$major-$minor-$year$month$day[-$patchlevel]", such as "0-5-20090313-p2". If the patch level is zero (identifying the first release of the given calendar date), the "-$patchlevel" suffix is omitted.

Major and minor numbers are incremented upon completion of significant objectives for the codebase (the most recent change, from 2-0 to 2-1, celebrated upgrading Melange from App Engine's Python 2.5 platform to its Python 2.7 platform).

== Creating and pushing the release commit ==

Once the releasing engineer has verified that the head of the master branch is fit to be used for a release, a new commit should be created to indicate the release itself. The content of this commit should be *only* a change to the "version" line of app/app.yaml.template. The commit log message of this commit should start with "Set new Melange version number to <version number> in app.yaml.template." and may or may not contain extra information germane to the release. After the releasing engineer has created the release commit it may be pushed to a branch for review (or directly to master if the releasing engineer is confident).

== Creating the release tag ==

Releases are also identified in source control by git tags. Tags are named with a "v" prefix prepended to the release identifier, so release "2-1-20140221" will be identified by git tag "v2-1-20140221". The release engineer is responsible for tagging the release in Melange's canonical repository.

== Deploying a release ==

From a mint checkout of the release commit, the commands to create and deploy a release are:
  # `git clean -xdf`
  # cp -r <wherever overrides are stored> .`
  # `virtualenv venv`
  # `venv/pip/install -U lxml setuptools`
  # `venv/bin/python bootstrap.py`
  # `bin/buildout`
  # `bin/paver build`
  # `bin/gen-app-yaml <app ID>` - Melange's production app ID is google-melange
  # `thirdparty/google_appengine/appcfg.py --oauth2 update build`

The elimination of the "overrides" step is tracked in [http://code.google.com/p/soc/issues/detail?id=1863 issue 1863].

== Shifting traffic to a release ==

The traffic splitting feature on [https://appengine.google.com/deployment?app_id=s~google-melange the production release dashboard] should be used to gradually shift traffic over to the new release while monitoring the logs for any stack traces or error messages that might indicate defects in the new release.

= Rollback of a release =

Should there be any critical issues that are noticed shortly after the release is deployed, and the release does not address an issue that is more critical than the new found issue, a rollback should be done. Due to the way AppEngine works it is possible to do such a rollback by setting the default version back to the previous release, for this reason the previous release version, and the one before that, should always be kept available.

Note:  If the new release is for an exploitable security issue, consider  deleting the old serving version as soon as logs have been gathered.  Otherwise, it can still be accessed directly via the versioned URL.