zulip/docs/subsystems/release-checklist.md

# Zulip server release checklist

This document has reminders of things one might forget to do when
preparing a new release.

### A week before the release

* For a major release (e.g. 4.0):
  * Upgrade all Python dependencies in
    `requirements` to latest upstream versions so they can burn in (use
    `pip list --outdated`).
  * [Upload strings to
    Transifex](../translating/internationalization.html#translation-process)
    using `push-translations`.  Post a Transifex
    [Announcement](https://www.transifex.com/zulip/zulip/announcements/)
    notifying translators that we're approaching a release.
  * Merge draft updates to the [changelog](../overview/changelog.md)
    with changes since the last release. While doing so, take notes on
    things that might need follow-up work or documentation before we
    can happily advertise them in a release blog post.
  * Inspect all `TODO/compatibility` comments for whether we can
    remove any backwards-compatibility code in this release.
* Create a burn-down list of issues that need to be fixed before we can
  release, and make sure all of them are being worked on.
* Draft the release blog post (a.k.a. the release notes) in Paper.  In
  it, list the important changes in the release, from most to least
  notable.

### Final release preparation

* Update the Paper blog post draft with any new commits.
* _Except minor releases:_ Download updated translation strings from
  Transifex and commit them.
* Use `build-release-tarball` to generate a release tarball.
* Test the new tarball extensively, both new install and upgrade from last
  release, on both Bionic and Focal.
* Repeat until release is ready.
* Send around the Paper blog post draft for review.
* Move the blog post draft to Ghost.  (For a draft in Dropbox Paper,
  use "··· > Export > Markdown" to get a pretty good markup
  conversion.)  Proofread the post, especially for formatting.  Tag
  the post with "Release announcements" in Ghost.

### Executing the release

* Create the release commit, on master (for major releases) or on the
  release branch (for minor releases):
  * Copy the Markdown release notes for the release into
    `docs/overview/changelog.md`.
  * Update `ZULIP_VERSION` and `LATEST_RELEASE_VERSION` in `version.py`.
  * _Except minor releases:_ Update `API_FEATURE_LEVEL` to a feature
    level for the final release, and document a reserved range.
* Tag that commit with an unsigned Git tag named the release number.
* Use `build-release-tarball` to generate a final release tarball.
* Push the tag and release commit.
* Copy the tarball to `zulip.org`, and run
  `/etc/zulip/ship-release.sh` on it; this will put it in place,
  update the latest symlink, and update the SHA256 sums.
* Post the release by [editing the latest tag on
  GitHub](https://github.com/zulip/zulip/tags); use the text from
  `changelog.md` for the release notes.

  **Note:** This will trigger the [GitHub action](https://github.com/zulip/zulip/blob/master/tools/oneclickapps/README.md)
  for updating DigitalOcean one-click app image. The action uses the latest release
  tarball published on `zulip.org` for creating the image.
* Update the [Docker image](https://github.com/zulip/docker-zulip) and
  do a release of that.
* Update the image of DigitalOcean one click app using
  [Fabric](https://github.com/zulip/marketplace-partners) and publish
  it to DO marketplace.
* Publish the blog post; check the box to "send by email."
* Email [zulip-announce](https://groups.google.com/g/zulip-announce),
  post to [#announce](https://chat.zulip.org/#narrow/stream/1-announce),
  and [send a tweet](https://twitter.com/zulip).

### Post-release

* Following a major release (e.g. 4.0):
  * Create a release branch (e.g. `4.x`).
  * On the release branch, update `ZULIP_VERSION` in `version.py` to
    the present release with a `+git` suffix, e.g. `4.0+git`.
  * On master, update `ZULIP_VERSION` to the future major release with
    a `-dev+git` suffix, e.g. `5.0-dev+git`.  Make a Git tag for this
    update commit with a `-dev` suffix, e.g. `5.0-dev`.  Push the tag
    to both zulip.git and zulip-internal.git to get a correct version
    number for future Cloud deployments.
* Following a minor release (e.g. 3.2):
  * On the release branch, update `ZULIP_VERSION` to the present
    release with a `+git` suffix, e.g. `3.2+git`.
  * Cherry-pick the changelog changes back to `master`.
* Consider removing a few old releases from ReadTheDocs; we keep about
  two years of back-versions.