releases.rst

title:	Releases
description:	The Deis software release process.

Release Checklist

These instructions are to assist the Deis maintainers with creating a new Deis product release. Please keep this document up-to-date with any changes in this process.

deis repo

• If this release was managed as a milestone in GitHub:

  • Create the next deis milestone
  • Move any deis open issues from the current release to the next milestone
  • Close the current deis milestone

• Create a branch for the release PR: git checkout -b release-X.Y.Z

• Update CHANGELOG.md using the changelog script

  • ./contrib/util/generate-changelog.sh vU.V.W | cat - CHANGELOG.md > tmp && mv tmp CHANGELOG.md substituting the previous release for vU.V.W.
  • proofread the new CHANGELOG.md to ensure it was generated correctly and edit HEAD at the top to vX.Y.Z (the current release)

• Update version strings with the bumpver tool:

  $ ./contrib/bumpver/bumpver X.Y.Z \
      version/version.go \
      client/deis.py \
      client/setup.py \
      deisctl/deis-version \
      deisctl/deisctl.go \
      deisctl/README.md \
      contrib/coreos/user-data \
      controller/deis/__init__.py \
      README.md

• Edit deisctl/cmd/cmd.go and change the default in the RefreshUnits usage string (near the bottom of the file) from [master] to [vX.Y.Z].

• Examine the output of git grep vU.V.W to ensure that no old version strings were missed

• Commit and push the deis/deis release and tag

  • git commit -a -m 'chore(release): update version to vX.Y.Z'
  • git push origin release-X.Y.Z

• When the PR is approved and merged, tag it in master

  • git checkout master && git pull
  • git tag vX.Y.Z
  • git push --tags origin vX.Y.Z

• Publish CLI to pypi.python.org

  • cd client && python setup.py sdist upload
  • use testpypi.python.org first to ensure there aren't any problems

• Continuous delivery jobs at ci.deis.io will update the deis CLI. Double-check that the current binary installers are publicly downloadable from the opdemand S3 bucket.

deis.io repo

• Update deis.io installer scripts to point to new versions by default

  • update https://github.com/deis/deis.io/blob/gh-pages/deis-cli/install.sh
  • update https://github.com/deis/deis.io/blob/gh-pages/deisctl/install.sh

Documentation

• (CHANGELOG.md files were regenerated and committed above.)
• Docs are automatically published to http://docs.deis.io (the preferred alias for deis.readthedocs.org)

• Log in to the http://deis.readthedocs.org admin

  • add the current release to the list of published builds
  • remove the oldest release from the list of published builds
  • rebuild all published versions so their "Versions" index links are updated

• Publish docs to pythonhosted.org/deis

  • from the project root, run make -C docs clean zipfile
  • the zipfile will be at docs/docs.zip
  • log in to http://pypi.python.org/ and use the web form at the Deis Pypi page to upload the zipfile

• Check documentation for deis/* projects at the Docker Hub

  • click "Settings" for each project (deis/controller, deis/cache, etc.)
  • paste the contents of each README.md into the "long description" field if there are discrepencies

• For a milestone release, create release notes docs

  • follow the format of previous release notes
  • summarize all work done since the previous release
  • visit all deis/* project issues to make sure we don't miss any contributors for the "Community Shout-Outs" section
  • include "what's next" and "future directions" sections
  • add Markdown version of release notes to deis/deis.io website project

• For a patch release, paste the new CHANGELOG.md section as GitHub release notes

Post-Release

• Update the #deis IRC channel topic to reference the newly released version

• For a milestone release, update HipChat channel topics to reference the next planned version

• Create a branch for the post-release PR: git checkout -b release-X.Y.Z+git

• Update version strings to vX.Y.Z+git with the bumpver tool:

  $ ./contrib/bumpver/bumpver X.Y.Z+git \
      version/version.go \
      client/deis.py \
      deisctl/deis-version \
      deisctl/deisctl.go \
      controller/deis/__init__.py \
      README.md

• Edit deisctl/cmd/cmd.go and change the default in the RefreshUnits usage string (near the bottom of the file) from [vX.Y.Z] to [master].

• Create a pull request for vX.Y.Z+git

  • git commit -a -m 'chore(release): update version in master to vX.Y.Z+git'

• Ensure that this PR is merged before others are allowed to be merged!