

# 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:
  1. `make gitclean`
  1. `make setup`
  1. `make ptest`
  1. `make do-release`

Do **NOT** release if all tests do not pass.

If you need to specify a specific version label, you can do:
> `make do-release VERSION=2-1-2014XXYY-p1`

If you don't want to update the version string in app.yaml, you can use `make do-dev-release`.  It will name its releases based on the output of `git describe --tags`.  For example:
  * `make do-dev-release APP=melange-hrd-dev`
  * `make do-dev-release APP=google-melange`


## Shifting traffic to a release

The traffic splitting feature on [the production release dashboard](https://appengine.google.com/deployment?app_id=s~google-melange) 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.