Skip to content

Release procedure

Jump to bottom Edit New page
Simon Stridsberg edited this page Mar 18, 2024 · 49 revisions

Release time schedule (rough)

  • There are two types of releases
    • Major releases with a version x.y.0
    • Regular releases with a version x.y.z where z is greater than zero
  • There are two major 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

Prep work

Before starting the release process, some updates are needed, mostly in the documentation.

Release notes (major release only)

Release notes are split in two documents, one listing changes and one explaining the actions needed to upgrade. These documents must be completed before the release day, and can be conveniently be started from a template:

git cherry-pick b2f5cf3c1d75f5ab72df40de87c0ddbab6639a35

This cherry-pick creates the following files:

  • doc/sphinx/whats-new/changes-trunk.rst
  • doc/sphinx/whats-new/upgrading-trunk.rst

They will later be referred to as just changes-trunk.rst and upgrading-trunk.rst. In this process doc/sphinx/whats-new/index.rst (later referred to as just index.rst) is updated with a minor conflict to solve.

Change log

The file doc/changes.rst should also be updated to reflect changes since the previous releases. This document may refer to internal changes not necessarily visible to end-users.

VRT history

We record changes to the VRT API and to some extent other APIs in include/vrt.h, it should be updated to reflect changes since the last release.

Regular releases are not supposed to break the VRT API and only additions are expected during this review.

Bundled VCL (major release only)

Update etc/devicedetect.vcl to the upstream devicedetect VCL. Commit this file with an "Updating devicedetect.vcl to upstream" message and push it.

Release steps

Branch creation (major release only)

Major releases branch out from trunk to a branch called 'x.y'. At this point all the prep work must be complete. The release itself will be tagged on that branch.

Start from a clean checkout of an up to date master branch:

git push origin master:x.y

This creates a new 'x.y' branch in the repository with the same HEAD as master.

Release changes

All release changes happen on the 'x.y' branch:

git checkout x.y

Make sure that this branch is up to date before proceeding.

  • Edit doc/changes.rst to change 'NEXT' to the new x.y.z release number.
    • Run rst2html --halt=2 doc/changes.rst >> /dev/null to detect syntax errors before committing. (they will fail make distcheck)
  • For a major release, edit changes-trunk.rst and upgrading-trunk.rst
    • Replace $NEXT_RELEASE or CURRENT placeholders with x.y
    • Remove remaining mentions of those being work in progress documents
    • Rename the files, replacing trunk with x.y
  • For a major release, edit index.rst
    • Replace trunk, $NEXT_RELEASE or CURRENT placeholders with x.y
  • Update configure.ac with the new version number and possibly the Copyright year.
  • Update lib/libvarnish/version.c copyright year
  • For a major release, update the "Via:" header in bin/varnishd/cache/cache_req_fsm.c (Not applicable since 7.2.0)
  • Update version of include/vrt.h as applicable
    • For a major release
      • Increment VRT_MAJOR_VERSION
      • Reset VRT_MINOR_VERSION to zero
    • For a regular release
      • Increment VRT_MINOR_VERSION if something was added to the VRT API
  • If VRT_MAJOR_VERSION was updated, edit bin/varnishtest/tests/m00003.vtc to reflect the new major version.
  • 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
  • Create a pull request targeting the 'x.y' branch
    • Add this checklist to the pull request description: 
      Reviewers must check the following items:

- [ ] Release notes are complete (major release only)
- [ ] Release notes no longer target trunk (major release only)
- [ ] The change log is populated
- [ ] The VRT history in `include/vrt.h` is populated
- [ ] The VRT history refers to the next VRT version
- [ ] The macro `VRT_MAJOR_VERSION` was updated if applicable
- [ ] The macro `VRT_MINOR_VERSION` was updated if applicable
- [ ] The new VRT version follows releases guidelines
- [ ] The new VRT version matches the one from the VRT history
- [ ] Bundled `devicedetect.vcl` was updated (major release only)
- [ ] Running `./autogen.des && make distcheck` succeeds
- [ ] The version in `configure.ac` is correct
- [ ] The copyright notice in `configure.ac` covers the current year
- [ ] The copyright output in `lib/libvarnish/version.c` covers the current year
- [ ] There are no other changes than the ones listed above
  • 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 archive is the release
  • Tag the release
    • git tag -a -m "Releasing x.y.z" varnish-x.y.z HEAD
    • git push origin varnish-x.y.z

Tracking the release in trunk's history (major release only)

In order for the tag of a major release to exist in the trunk history, we merge the tag back in the master branch. At this point the 'x.y' branch will diverge from trunk. For this we create a merge commit that will not only bring the release changes back to the master branch, but also keep the version to trunk on this branch.

This puts the release tag back into the trunk timeline, making it visible for git queries for what releases contain a given commit, and enables other related git usages.

At this point the local branch should be 'x.y':

  • Switch back to the master branch
    • git checkout master
  • Merge the tag, except the version update
    • git merge --no-ff --no-commit --edit varnish-x.y.0
    • Edit configure.ac setting the version back to trunk
    • git add configure.ac
    • git commit
  • Push the master branch to the repository:
    • git push origin master

Update the homepage

  • 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
    • _templates/navigation.html
  • 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

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!

Add a custom footer
Add a custom sidebar
Clone this wiki locally