Contour Release Process

Minor Release Process

Overview

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
  • a release tag to be created
  • an Operator release
  • a GitHub release with release notes
  • public communication
  • cleanup

Process

Set environment variables

Set environment variables for use in subsequent steps:

export CONTOUR_RELEASE_VERSION=v1.11.0
export CONTOUR_RELEASE_VERSION_MAJOR=1
export CONTOUR_RELEASE_VERSION_MINOR=11
export CONTOUR_PREVIOUS_VERSION=v1.10.0

export CONTOUR_UPSTREAM_REMOTE_NAME=upstream
export CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME=upstream

Update the website with release-specific information

  1. Check out main, ensure it’s up to date, and ensure you have a clean working directory.
  2. Create a new local feature branch from main.

  3. Generate a new set of versioned docs:

     go run ./hack/release/prepare-release.go $CONTOUR_RELEASE_VERSION
  4. Add the new release to the compatibility matrix (/site/_resources/compatibility-matrix.md).
  5. Run through upgrading from previous version and document upgrade instructions for the new release (/site/_resources/upgrading.md).
    1. Check the example deployment manifests for any significant diffs that may need a call out in upgrading instructions and release notes: git log -p $CONTOUR_PREVIOUS_VERSION..HEAD examples/contour
    2. Deploy current release example deployment: /integration/testsuite/install-contour-release.sh $CONTOUR_PREVIOUS_VERSION
    3. Deploy an example workload: kubectl apply -f https://projectcontour.io/examples/kuard.yaml
    4. Ensure workload is reachable, check status of Contour components/Envoy daemonset
    5. Deploy main branch (new release): /integration/testsuite/install-contour-working.sh
    6. Ensure upgrade finishes, Contour/Envoy deployments healthy, and example workload is reachable as expected
  6. Commit all changes, push the branch, and PR it into main.

Note: the PR will probably fail the siteproof check due to #2032. It’s a good idea to scan the CI log for any true issues.

Branch and tag release

  1. Check out main, ensure it’s up to date, and ensure you have a clean working directory.

  2. Create a local release branch:

     git checkout -b release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  3. Push the branch to github.com/projectcontour/contour:

     git push --set-upstream ${CONTOUR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  4. Update the deployment YAML and create a local tag:

     ./hack/release/make-release-tag.sh main $CONTOUR_RELEASE_VERSION

  5. Push the branch to github.com/projectcontour/contour:

     git push ${CONTOUR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  6. Push the tag to github.com/projectcontour/contour:

     git push ${CONTOUR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}

Release the operator

  1. Verify the operator example manifest is in-sync with the Contour example manifests. If not, submit a PR to update the operator and get it merged before proceeding. Check out main, ensure it’s up to date, and ensure you have a clean working directory.

  2. Create a local release branch:

     git checkout -b release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  3. Push the branch to github.com/projectcontour/contour-operator:

     git push --set-upstream ${CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  4. Update the deployment YAML and create a local tag:

     ./hack/release/make-release-tag.sh main $CONTOUR_RELEASE_VERSION

  5. Push the branch to github.com/projectcontour/contour-operator:

     git push ${CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  6. Push the tag to github.com/projectcontour/contour-operator:

     git push ${CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}

Update quickstart YAML redirects

  1. Check out main, ensure it’s up to date, and ensure you have a clean working directory.
  2. Create a new local feature branch from main.
  3. Update netlify.toml to redirect quickstart links to the new release branch.
  4. Commit all changes, push the branch, and PR it into main.

Do the Github release and write release notes

Now you have a tag pushed to Github, go to the release tab on github, select the tag and write up your release notes.

Be mindful of changes to the example deployment YAMLs that were documented in the upgrade instructions step above as these are likely very important to include in the release notes.

Note: Filter on the Github label “release note” and Github milestone which should include any PRs which should be called out in the release notes.

Toot your horn

  • Post a blog entry to projectcontour.io
  • Post a note to the #contour channel on k8s slack, also update the /topic with the current release number
  • Post a note to the #project-contour channel on the vmware slack, also update the /topic with the current release number
  • Send an update to the cncf-contour-users mailing list

File issues

If you encountered any problems or areas for improvement while executing the release, file issues before you forget.

Patch Release Process

Overview

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
  • an Operator release
  • a GitHub release with release notes
  • public communication
  • cleanup

Process

Set environment variables

Set environment variables for use in subsequent steps:

export CONTOUR_RELEASE_VERSION=v1.11.1
export CONTOUR_RELEASE_VERSION_MAJOR=1
export CONTOUR_RELEASE_VERSION_MINOR=11
export CONTOUR_PREVIOUS_VERSION=v1.11.0
export CONTOUR_PREVIOUS_MINOR_VERSION=v1.10.0

export CONTOUR_UPSTREAM_REMOTE_NAME=upstream
export CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME=upstream

Cherry-pick relevant commits into release branch

  1. Get a list of commit SHAs from main to backport.
  2. Check out the release branch for the minor version you’re patching (i.e. release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}), ensure it’s up to date, and ensure you have a clean working directory.
  3. Create a new local feature branch from the release branch.

  4. Cherry-pick each commit from Step 1, fixing any conflicts as needed:

     # repeat for each SHA
 git cherry-pick <SHA>
  5. Commit all changes, push the branch, and PR it into the release branch.

Update the website with release-specific information

  1. Check out main, ensure it’s up to date, and ensure you have a clean working directory.
  2. Create a new local feature branch from main.

  3. Generate a new set of versioned docs:

     go run ./hack/release/prepare-release.go $CONTOUR_PREVIOUS_VERSION $CONTOUR_RELEASE_VERSION
  4. Add the new release to the compatibility matrix (/site/_resources/compatibility-matrix.md).
  5. Run through upgrading from previous version and document upgrade instructions for the new release (/site/_resources/upgrading.md).
    1. Check the example deployment manifests for any significant diffs that may need a call out in upgrading instructions and release notes: git log -p $CONTOUR_PREVIOUS_MINOR_VERSION..HEAD examples/contour
    2. Deploy current release example deployment: /integration/testsuite/install-contour-release.sh $CONTOUR_PREVIOUS_MINOR_VERSION
    3. Deploy an example workload: kubectl apply -f https://projectcontour.io/examples/kuard.yaml
    4. Ensure workload is reachable, check status of Contour components/Envoy daemonset
    5. Deploy main branch (new release): /integration/testsuite/install-contour-working.sh
    6. Ensure upgrade finishes, Contour/Envoy deployments healthy, and example workload is reachable as expected
  6. Commit all changes, push the branch, and PR it into main.

Update YAML and tag release

  1. Check out the release branch, ensure it’s up to date, and ensure you have a clean working directory.

  2. Update the deployment YAML and create a local tag:

     ./hack/release/make-release-tag.sh $CONTOUR_PREVIOUS_VERSION $CONTOUR_RELEASE_VERSION

  3. Push the branch to github.com/projectcontour/contour:

     git push ${CONTOUR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  4. Push the tag to github.com/projectcontour/contour:

     git push ${CONTOUR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}

Release the operator

  1. Verify the operator example manifest is in-sync with the Contour example manifests. If not, submit a PR to update the operator and get it merged before proceeding.
  2. Get a list of commit SHAs from main to backport.
  3. Check out the release branch for the minor version you’re patching (i.e. release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}), ensure it’s up to date, and ensure you have a clean working directory.
  4. Create a new local feature branch from the release branch.

  5. Cherry-pick each commit from Step 1, fixing any conflicts as needed:

     # repeat for each SHA
 git cherry-pick <SHA>

  6. Commit all changes, push the branch, and PR it into the release branch.

  7. Check out the release branch, ensure it’s up to date, and ensure you have a clean working directory.

  8. Update the deployment YAML and create a local tag:

     ./hack/release/make-release-tag.sh $CONTOUR_PREVIOUS_VERSION $CONTOUR_RELEASE_VERSION

  9. Push the branch to github.com/projectcontour/contour-operator:

     git push ${CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}

  10. Push the tag to github.com/projectcontour/contour-operator:

     git push ${CONTOUR_OPERATOR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}

Do the Github release and write release notes

Now you have a tag pushed to Github, go to the release tab on github, select the tag and write up your release notes.

Be mindful of changes to the example deployment YAMLs that were documented in the upgrade instructions step above as these are likely very important to include in the release notes. These should be unlikely in a patch release.

Note: Filter on the Github label “release note” and Github milestone which should include any PRs which should be called out in the release notes.

Toot your horn

  • Post a note to the #contour channel on k8s slack, also update the /topic with the current release number
  • Post a note to the #project-contour channel on the vmware slack, also update the /topic with the current release number
  • Send an update to the cncf-contour-users mailing list

File issues

If you encountered any problems or areas for improvement while executing the release, file issues before you forget.

Ready to try Contour?

Read our getting started documentation.

Getting Started