Istio Release Management

This page describes the process of creating an Istio release.

Start of the release process:

• Create an Istio wiki page for release, for an example, see the 1.6 version
  • Make sure the wiki reflects the most accurate dates related to important events during the release (for e.g: Code Freeze, Release Dates, Testing Days)
  • Add the names and github handles of release managers
• Track all steps needed to prepare release build and branch. Pull requests for the individual steps can be found in the comments.

⚠️ The build tools will initially have to be from master, but this should be updated to the release one as soon as it's built. Examples: https://github.com/istio/common-files/pull/241/files and here: https://github.com/istio/tools/pull/932/files

• Important milestones during the release:
  • Code Freeze
  • Testing Days
  • Release Date
• Create a Slack channel to allow for release-specific communication. It's also helpful to have a pinned thread in this channel indicating what issues are remaining to be merged for that release.
• Scrape github issues which targets the release, triage the ones missing priority, and dump Release Blockers and P0s into a spreadsheet for tracking. For example, here is the tracking sheet for 1.8. To help making generating the issue tracking spreadsheet easier: this example GraphQL Query to list issues targeting 1.8 milestone could be used in github GraphQL explorer, and this code snippet could take the JSON output of the GraphQL query and generate a CSV from it which could be dumped into Google sheet.

During the release:

• Publish and trigger beta builds to test for testing days(example from 1.5):
  • trigger build
  • trigger publish
• Prepare a document to track release blockers (1.5 version 1.6 version)
• Preparing for community testing days:
  • Create a testing spreadsheet. Priorities should be reviewed with the workgroup leads and docs team to make sure they are accurate. The documentation team should be able to figure out what pages are visited most and what they are most concerned about. The workgroup leads should be able to say what their area of functionality is most concerned with.
  • Add the date and times for testing days to the Istio Community Calendar (Lin Sun or Shweta can help with this)
  • Announce the date/time and details about testing days on discuss.istio.io and Slack. (previous release examples: (release-1.5, release-1.4, release-1.6). This should be done a couple of days ahead of time so as to allow people to see it, but not long enough for them to forget.
  • Test the base image of Istio: https://hub.docker.com/layers/istio/base/1.5-dev.2/images/sha256-4d3608f0c33d9dabc204929ee953e980c23760e3258f99f4206a4f8b04475fd9?context=explore for vulnerabilities and build a new image. John Howard has the rights to push images to docker hub.
  • Verify that Istio downloads. In 1.6, the URL changed. It might be good for a release manager just to make sure that they can do a quick install.
• Checking with work group lead and update feature status page.

Writing release notes and upgrade notes

• Istio collects release notes and upgrade notes on a per-pull-request basis. For each pull request with user facing changes, the maintainers for a work group add the appropriate release notes. At the end of a release, the release notes tooling is run to generate the release notes and upgrade notes for a release. These should then be reviewed by the documentation team and release managers. It may be helpful to review the release notes schema.

Preparing for Release day

• Conformance tests should be run for 48 hours before releases. In the past, this has been done by John Howard and Eric Van Norman. The docs team should be contacted at the same time.
• Prepare release notes/upgrade notes/release announcement for a given release:
  • Work with the docs team to get the release notes and upgrade notes pull requests ready. The release will also need an announcement. Previously, Dan Ciruli has written with the announcements. It may be a good idea to combine all three pull requests into a single one before merging.
• Build and publish the final release
• Work with the docs team to prepare the docs, so that istio.io link points to the new release and preliminary.istio.io points to the next release. The steps for this are discussed in the readme on github.com/istio/istio.io

General Notes

• PRs to the release branch should be cherry-picked from master to have SME approval
• If that’s not possible, try and add relevant WG members for approvals before merging
• You can test any release before publishing (after merging the trigger-build PR). Images can be tested with --set hub=gcr.io/istio-prerelease-testing.
• There were some issues with the switchover of istio.io - keep in touch with the docs WG to make sure these will be resolved
• Enforcing a code freeze was very helpful for the 1.6 release.

End of Life

• Testing must be disabled for the release
• A flush release must be completed and announced as the final release. A flush release is a release that contains all remaining pull requests/commits at the time that the release is made.
• An End Of Life announcement must be sent out 30 days before the final release (e.g. https://istio.io/latest/news/support/announcing-1.4-eol/ ).
• A final announcement must be sent on the End of Life date (e.g. https://istio.io/latest/news/support/announcing-1.4-eol-final/ )
• After the final EOL date, no further releases will be developed and the only code changes accepted will be security fixes. This allows vendors to share the effort on fixes.