Project: Contour (Orchestration & Management / Service Proxy)
File: release-process.md

title: Contour Release Process layout: page A minor release is e.g. `v1.11.0`. A minor release requires: website updates a release branch to be created YAML to be customized an update to dependabot config a release tag to be created a GitHub release with release notes submitting a Gateway API conformance report (if applicable) public communication cleanup Set environment variables for use in subsequent steps: ```bash export CONTOURRELEASEVERSION=v1.11.0 export CONTOURRELEASEVERSION_MAJOR=1 export CONTOURRELEASEVERSION_MINOR=11 export KUBERNETESMINVERSION=1.20 export KUBERNETESMAXVERSION=1.22 export CONTOURUPSTREAMREMOTE_NAME=upstream ``` Check out `main`, ensure it's up to date, and ensure you have a clean working directory. Create a new local feature branch from `main`. Generate a new set of versioned docs, plus a changelog: ```bash go run ./hack/release/prepare-release.go $CONTOURRELEASEVERSION $KUBERNETESMINVERSION $KUBERNETESMAXVERSION ``` Proofread the release notes and do any reordering, rewording, reformatting necessary, including editing or deleting the "Deprecation and Removal Notices" section. Add the new release to the compatibility matrix (`site/content/resources/compatibility-matrix.md`). Add the new release to the compatibility YAML (`/versions.yaml`). Be sure to mark this new version as supported and mark oldest currently supported version as no longer supported. Update `.github/workflows/trivy-scan.yaml` to add new release branch and remove oldest listed (should always be 3 latest branches listed). Commit all changes, push the branch, and PR it into `main`. Check out `main`, ensure it's up to date, and ensure you have a clean working directory. Create a local release branch: ```bash git checkout -b release-${CONTOURRELEASEVERSIONMAJOR}.${CONTOURRELEASEVERSIONMINOR} ``` Push the branch to `github.com/projectcontour/contour`: ```bash git push --set-upstream ${CONTOURUPSTREAMREMOTENAME} release-${CONTOURRELEASEVERSIONMAJOR}.${CONTOURRELEASEVERSION_MINOR} ``` Update the deployment YAML and create a local tag: ```bash ./hack/release/make-release-tag.sh main $CONTOURRELEASEVERSION ``` Push the branch to `github.com/projectcontour/contour`: ```bash git push ${CONTOURUPSTREAMREMOTENAME} release-${CONTOURRELEASEVERSIONMAJOR}.${CONTOURRELEASEVERSION_MINOR} ``` Push the tag to `github.com/projectcontour/contour`: ```bash git push ${CONTOURUPSTREAMREMOTENAME} ${CONTOURRELEASE_VERSION} ``` Update the `.github/dependabot.yml` file to update the target branches for Dependabot scanning. The latest minor (N) and two previous minors should be scanned (N-1 and N-2). If the compatible Gateway API version has been bumped in this release, a conformance report should be reported upstream. Currently the process is manual but we have automated running the conformance suite and report generation in CI on release tags. Steps to submit a conformance report are: Find the corresponding `Build and push a release` GitHub Action workflow run for this release from Download the `gateway-conformance-report` artifact from the workflow run and unzip Check it for accuracy, and make a PR like to the `gateway-api` repo with the content of the report Check out `main`, ensure it's up to date, and ensure you have a clean working directory. Create a new local feature branch from `main`. Update `netlify.toml` to redirect Contour quickstart links to the new release branch. Commit all changes, push the branch, and PR it into `main`. Now you have a tag pushed to Github, go to the release tab on github, select the tag and paste in the release notes that were generated previously. A patch release is e.g. `v1.11.1`. A patch release requires: patches to be cherry-picked onto the existing release branch website updates YAML to be customized a release tag to be created a GitHub release with release notes submitting a Gateway API conformance report (if applicable) public communication cleanup Set environment variables for use in subsequent steps: ```bash export CONTOURRELEASEVERSION=v1.11.1 export CONTOURRELEASEVERSION_MAJOR=1 export CONTOURRELEASEVERSION_MINOR=11 export CONTOURPREVIOUSVERSION=v1.11.0 export CONTOURUPSTREAMREMOTE_NAME=upstream ``` Get a list of commit SHAs from `main` to backport. Check out the release branch for the minor version you're patching (i.e. `release-${CONTOURRELEASEVERSIONMAJOR}.${CONTOURRELEASEVERSIONMINOR}`), ensure it's up to date, and ensure you have a clean working

Create a new local feature branch from the release branch. Cherry-pick each commit from Step 1, fixing any conflicts as needed: ```bash git cherry-pick <SHA> ``` Commit all changes, push the branch, and PR it into the release branch. Check out `main`, ensure it's up to date, and ensure you have a clean working directory. Create a new local feature branch from `main`. Create release notes in `changelogs/CHANGELOG-<version>.md`. Add the new release to the compatibility matrix (`/site/content/resources/compatibility-matrix.md`). Add the new release to the compatibility YAML (`/versions.yaml`). Commit all changes, push the branch, and PR it into `main`. Check out the release branch, ensure it's up to date, and ensure you have a clean working directory. Update the deployment YAML and create a local tag: ```bash ./hack/release/make-release-tag.sh $CONTOURPREVIOUSVERSION $CONTOURRELEASEVERSION ``` Push the branch to `github.com/projectcontour/contour`: ```bash git push ${CONTOURUPSTREAMREMOTENAME} release-${CONTOURRELEASEVERSIONMAJOR}.${CONTOURRELEASEVERSION_MINOR} ``` Push the tag to `github.com/projectcontour/contour`: ```bash git push ${CONTOURUPSTREAMREMOTENAME} ${CONTOURRELEASE_VERSION} ``` If the compatible Gateway API version has been bumped in this release, a conformance report should be reported upstream. Currently the process is manual but we have automated running the conformance suite and report generation in CI on release tags. Steps to submit a conformance report are: Find the corresponding `Build and push a release` GitHub Action workflow run for this release from Download the `gateway-conformance-report` artifact from the workflow run and unzip Check it for accuracy, and make a PR like to the `gateway-api` repo with the content of the report Now you have a tag pushed to Github, go to the release tab on github, select the tag and paste in the release notes that were generated previously. An release-candidate release is e.g. `v1.23.0-rc.1`. A release-candidate requires: a branch off of `main` for the release-candidate YAML to be customized a release tag to be created a GitHub release with release notes public communication cleanup Set environment variables for use in subsequent steps: ```bash export CONTOURRELEASEVERSION=v1.23.0-rc.1 export CONTOURPREVIOUSVERSION=v1.22.1 export KUBERNETESMINVERSION=1.23 export KUBERNETESMAXVERSION=1.25 export CONTOURUPSTREAMREMOTE_NAME=upstream ``` Typically we will branch off of `main` to cut an RC of an upcoming release and add the release tag on that branch. This process is easier than managing a `release-*` branch and having to cherry-pick changes over from `main` for additional commits. Make sure `main` is up to date Create a new local branch from `main` (e.g. `release-1.23.0-rc.1`) Commit all changes, push the branch to `github.com/projectcontour/contour`. Ensure the RC branch you created above is clean and up to date. Generate a changelog (the `prepare-release.go` script should detect the version is an RC and only generate a changelog): ```bash go run ./hack/release/prepare-release.go $CONTOURRELEASEVERSION $KUBERNETESMINVERSION $KUBERNETESMAXVERSION ``` Proofread the release notes and do any reordering, rewording, reformatting necessary. Commit all changes, push the branch to `github.com/projectcontour/contour`. Check out the RC branch, ensure it's up to date, and ensure you have a clean working directory. Update the deployment YAML and create a local tag: ```bash ./hack/release/make-release-tag.sh $CONTOURPREVIOUSVERSION $CONTOURRELEASEVERSION ``` Push the branch to `github.com/projectcontour/contour` (e.g. `git push upstream release-1.23.0-rc.1`). Push the tag to `github.com/projectcontour/contour`: ```bash git push ${CONTOURUPSTREAMREMOTENAME} ${CONTOURRELEASE_VERSION} ``` Now you have a tag pushed to Github, go to the release tab on github, select the tag and paste in the release notes that were generated previously. After any release, a few communications should be sent out to notify users. Post a note to the #contour channel on k8s slack, also update the /topic with the current release number Send an update to the If you encountered any problems or areas for improvement while executing the release, file issues before you forget.