Release procedure

Release time schedule (rough)

• There are two major (x.y.0) releases per year, around March 15th and September 15th
• The whole months of March and September are freeze periods
  • Nothing should be pushed directly except documentation or purely cosmetic changes
  • Actual changes should be shelved as pull requests but may be merged for the release
• At the end of a freeze period we put the version back to trunk on the master branch
  • We can kick off trunk release notes right away: git cherry-pick b2f5cf3c1d75f5ab72df40de87c0ddbab6639a35 (with a minor conflict to solve)

Preparing the documentation

This document assumes that the doc/changes.rst, doc/sphinx/whats-new/changes-trunk.rst and doc/sphinx/whats-new/upgrading-trunk.rst files are already updated for the next release in trunk, using -CURRENT as the placeholder for references to what will become the next release.

x.y.0 Source release steps

• Start on a clean checkout of the master branch
  • If you use multiple git checkouts, make sure you do a git pull initially so you don't miss any commits pushed elsewhere.
• Update etc/devicedetect.vcl to the upstream devicedetect VCL
• Commit this file under an "Updating devicedetect.vcl to upstream" message and push it.
• All x.y.0 releases are branched out from trunk to a branch called 'x.y'. All release preparation is done on that branch. The release itself will be tagged on that branch.
  • git checkout -b x.y
• Immediately push the 'x.y' branch while it is on the same commit as the master branch, it will serve as the base branch of a pull request.
  • git push --set-upstream origin x.y
• Update doc/changes.rst, and change 'NEXT_RELEASE' to the new release number.
  • Run rst2html --halt=2 changes.rst >> /dev/null to detect syntax errors before commiting. (they will fail make distcheck)
• Edit doc/sphinx/whats-new/changes-trunk.rst and doc/sphinx/whats-new/upgrading-trunk.rst
  • Rename the files to the correct *-x.y.rst names for the new version.
  • Edit the files changing any -CURRENT references to -x.y references
  • Edit doc/sphins/whats-new/index.rst -CURRENT references to -x.y references
• Update configure.ac with the new version number and possibly the Copyright year.
• Update lib/libvarnish/version.c copyright year
• Update the "Via:" header in bin/varnishd/cache/cache_req_fsm.c
• Update version of include/vrt.h as applicable.
• Update the copyright years in the 'varnishd -V' example in doc/sphinx/index.rst to match reality
• Commit these files under a "Prepare for x.y.z" message.
• Do a complete rebuild and distcheck: ./autogen.des && make distcheck
  • The resulting varnish-x.y.z.tar.gz tarball is the release
• Create a draft pull request for the 7.0 branch
  • Once the pull request is approved and merged, update your local copy: git pull --rebase
  • The release commit may have a different hash at this point
• Do a complete rebuild and distcheck, again: ./autogen.des && make distcheck
  • The resulting varnish-x.y.z.tar.gz tarball is the release
• Tag the release
  • git tag -a -m "Releasing x.y.z" varnish-x.y.z HEAD
• Create a merge commit with the release changes, bringing all the release changes back into trunk, everything except the version change in configure.ac. This puts the release tag back into the trunk timeline, making it visible for git queries for what releases contain a given commit.
  • git checkout master
  • git merge --no-ff --no-commit --edit varnish-x.y.z
  • Edit configure.ac setting the version back to trunk
  • git commit
• Push the master branch and release tag to the repository:
  • git push origin master varnish-x.y.z
• Switch to the homepage git repository, inside the R1/source/ directory and copy varnish-x.y.z.tar.gz as varnish-x.y.z.tgz in the releases/ directory.
• Add the release to www.varnish-cache.org in the homepage repository:
  • index.rst
  • releases/index.rst
  • releases/relx.y.z.rst
  • docs/index.rst
• Create a pull request with the homepage changes for the release.
• Add the release to tools/0200 for automatic doc-build on homepage (ask phk)
• Once merged, send announcement email to varnish-announce@. This Email should contain link to the tarball, the SHA256 of the tarball and a link to the changelog. The email needs to be approved in your mailman web interface: https://www.varnish-cache.org/lists/mailman/admindb/varnish-announce

Deploying packages

Packages are built using Circle-CI, with the help of the scripts in https://github.com/varnishcache/pkg-varnish-cache. A branch is created in the pkg-varnish-cache repository to keep a snapshot of the build scripts as they were at the time of release.

• In pkg-varnish-cache

$ git checkout master
$ git checkout -b x.y
$ git push -u origin x.y

The release branch is set to use this branch of pkg-varnish-cache by default.

• In varnish-cache release branch x.y edit and commit .circleci/config.yml, changing the pkg-commit parameter to x.y

The trunk build script's commit workflow is removed, and the nightly workflow becomes the new commit workflow.

• In varnish-cache release branch x.y edit and commit .circleci/config.yml the following:
  • Remove the commit workflow entirely
  • Remove the triggers section from the nightly workflow
  • Rename the nightly workflow to commit

Release package builds are started by triggering a custom workflow using Circle-CI's REST interface. Some additional parameters need to be set for the package build:

• dist-url: URL pointing to the release tarball to use for the package building. Without this, a local distribution tarball is built as part of the workflow.
• dist-url-sha256: SHA256-sum of the tarball to use for validating the download performed during package building.

When using the jay Circle-CI REST utility (a Varnish Software internal utility), the package build may be initiated with this command:

jay.sh -o varnishcache -r varnish-cache -b <x.y> -p dist-url:<http://varnish-cache.org/_downloads/varnish-x.y.tgz> -p dist-url-sha256:<SHA-sum>

This produces a link to the workflow in Circle-CI, where when finished the packages can be downloaded as an artifact.

These packages are the uploaded to packagecloud.

All done!