Release Candidate Process

This process applies to all releases candidates:

If you intent to release a new feature release, see the Feature Release Process section instead.

Note

The following commands have been validated when ran in the VM used in the Cilium development process. See Development Setup for detailed instructions about setting up said VM.

GitHub template process

  1. File a new release issue on GitHub, updating the title to reflect the version that will be released.

  2. Follow the steps in the issue template to prepare the release.

Reference steps for the template

Note

These instructions will generate a CHANGELOG based on the time when the start-release.sh script is run, so you should aim to coordinate with the core maintainers to complete these steps up until merging the PR before merging additional PRs from contributors.

  1. Ensure that the necessary features and fixes have been completed and merged into the branch for which the release candidate will happen.

    1. Update GitHub project and create vX.Y.Z-rcW+1 project if applicable.

    2. Update PRs / issues that were added to the vX.Y.Z-rcW project, but didn’t make it into this release into the vX.Y.Z-rcW+1 project.

    3. The Cilium Release Tool tool can help to manage these for you.

  2. Checkout the desired stable branch (can be master branch if stable branch was not created) and pull it:

    1. git checkout v1.0; git pull

  3. Run the release preparation script:

    1. contrib/release/start-release.sh

    Note

    Check to see if the AUTHORS file has any formatting errors (for instance, indentation mismatches) as well as duplicate contributor names, and correct them accordingly.

  4. Set the right version for the CustomResourceDefinitionSchemaVersion in the pkg/k8s/client by following these instructions:

    If you are doing the first RC for a new minor version, the validation schema version should be vX.Y.1 regardless of the value set in CustomResourceDefinitionSchemaVersion. For example, when setting up the first RC for Cilium 1.11, 1.11.0-rc1, the validation schema should be vX.Y+1.1 where X and Y are the major and minor versions used in the schema version of Cilium 1.10.

    If this is not the first RC run, and there is a branch for vX.Y:

    Run ./Documentation/check-crd-compat-table.sh vX.Y

    If a branch for vX.Y doesn’t exist yet, then manually ensure the CRD schema version has not been incremented in the case there were no changes. If there were changes to the CRD, then ensure it is incremented at most by 1 patch version.

  5. If this release will be based on the master branch rather than a stable branch, add the AUTHORS modifications to a new commit.

  6. Add all other modified files using git add and create a commit with the title Prepare for release vX.Y.Z-rcW+1.

  7. Prepare a pull request for the changes:

    1. contrib/release/submit-release.sh

  8. Ensure that the CI smoke tests and reviews are in for the pull request.

  9. Revert the top commit on the branch and push the branch again to GitHub.

  10. Follow standard procedures to get the aforementioned PR merged into the desired stable branch. See Submitting a pull request for more information about this process.

  11. Checkout out the stable branch and pull your merged changes:

    1. git checkout v1.0; git pull

  12. Check out the “Prepare for release” commit and create release tags:

    1. git checkout NNNN && contrib/release/tag-release.sh

    Note

    There are two tags that correspond to the same release because GitHub recommends using vx.y.z for release version formatting, and ReadTheDocs, which hosts the Cilium documentation, requires the version to be in format x.y.z For more information about how ReadTheDocs does versioning, you can read their Versions Documentation.

  13. Approve the release from the Release Image build UI.

  14. Once the release images are pushed, fetch the digests from the workflow.

  15. Prepare Helm changes for the release using the Cilium Helm Charts Repository and push the changes into that repository (not the main cilium repository):

    1. ./prepare_artifacts.sh /path/to/cilium/repository/checked/out/to/release/commit
    2. git push

  16. Wait for the Cilium Helm Charts Workflow to successfully deploy a cluster using the new Helm charts.

  17. Publish a GitHub release:

    Following the steps above, the release draft will already be prepared.

    1. Check the This is a pre-release box.

    2. Copy the official docker manifests for the release from the previous step into the end of the Github release announcement.

    3. Preview the description and then publish the release

  18. Announce the release in the #general channel on Slack. Sample text:

    1. :cilium-new: Cilium release candidate vX.Y.Z-rcN has been released:
    2. https://github.com/cilium/cilium/releases/tag/vX.Y.Z-rcN
    4. This release is not recommended for use in production clusters, but if
    5. you're in a position to pull it and try it out in staging / testing
    6. environments and report issues that you find, this will help us to put
    7. out a high-quality, stable final release :)