github.com/projectcontour/contour@v1.28.2/site/content/resources/release-process.md (about)

     1  ---
     2  title: Contour Release Process
     3  layout: page
     4  ---
     5  
     6  - [Minor release process][1]
     7  - [Patch release process][2]
     8  - [RC release process][3]
     9  
    10  # Minor Release Process
    11  
    12  ## Overview
    13  
    14  A minor release is e.g. `v1.11.0`.
    15  
    16  A minor release requires:
    17  - website updates
    18  - a release branch to be created
    19  - YAML to be customized
    20  - an update to dependabot config
    21  - a release tag to be created
    22  - a GitHub release with release notes
    23  - submitting a Gateway API conformance report (if applicable)
    24  - public communication
    25  - cleanup
    26  
    27  
    28  ## Process
    29  
    30  ### Set environment variables
    31  
    32  Set environment variables for use in subsequent steps:
    33  
    34  ```bash
    35  export CONTOUR_RELEASE_VERSION=v1.11.0
    36  export CONTOUR_RELEASE_VERSION_MAJOR=1
    37  export CONTOUR_RELEASE_VERSION_MINOR=11
    38  
    39  export KUBERNETES_MIN_VERSION=1.20
    40  export KUBERNETES_MAX_VERSION=1.22
    41  
    42  export CONTOUR_UPSTREAM_REMOTE_NAME=upstream
    43  ```
    44  
    45  ### Update the website with release-specific information
    46  
    47  1. Check out `main`, ensure it's up to date, and ensure you have a clean working directory.
    48  1. Create a new local feature branch from `main`.
    49  1. Generate a new set of versioned docs, plus a changelog:
    50      
    51      ```bash
    52      go run ./hack/release/prepare-release.go $CONTOUR_RELEASE_VERSION $KUBERNETES_MIN_VERSION $KUBERNETES_MAX_VERSION
    53      ```
    54  1. Proofread the release notes and do any reordering, rewording, reformatting necessary, including editing or deleting the "Deprecation and Removal Notices" section.
    55  1. Add the new release to the compatibility matrix (`site/content/resources/compatibility-matrix.md`).
    56  1. 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.
    57  1. Update `.github/workflows/trivy-scan.yaml` to add new release branch and remove oldest listed (should always be 3 latest branches listed).
    58  1. Commit all changes, push the branch, and PR it into `main`.
    59  
    60  ### Branch and tag release
    61  
    62  1. Check out `main`, ensure it's up to date, and ensure you have a clean working directory.
    63  1. Create a local release branch:
    64  
    65  ```bash
    66  git checkout -b release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}
    67  ```
    68  
    69  1. Push the branch to `github.com/projectcontour/contour`:
    70  
    71  ```bash
    72  git push --set-upstream ${CONTOUR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}
    73  ```
    74  
    75  1. Update the deployment YAML and create a local tag:
    76  
    77  ```bash
    78  ./hack/release/make-release-tag.sh main $CONTOUR_RELEASE_VERSION
    79  ```
    80  
    81  1. Push the branch to `github.com/projectcontour/contour`:
    82  
    83  ```bash
    84  git push ${CONTOUR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}
    85  ```
    86  
    87  1. Push the tag to `github.com/projectcontour/contour`:
    88  
    89  ```bash
    90  git push ${CONTOUR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}
    91  ```
    92  
    93  ### Update Dependabot configuration
    94  
    95  Update the `.github/dependabot.yml` file to update the target branches for Dependabot scanning.
    96  The latest minor (N) and two previous minors should be scanned (N-1 and N-2).
    97  
    98  ### Submit a Gateway API conformance report
    99  
   100  If the compatible Gateway API version has been bumped in this release, a conformance report should be reported upstream.
   101  Currently the process is manual but we have automated running the conformance suite and report generation in CI on release tags.
   102  Steps to submit a conformance report are:
   103  
   104  1. Find the corresponding `Build and push a release` GitHub Action workflow run for this release from [here][6]
   105  1. Download the `gateway-conformance-report` artifact from the workflow run and unzip
   106  1. Check it for accuracy, and make a PR like [this one][7] to the `gateway-api` repo with the content of the report
   107  
   108  ### Update quickstart YAML redirects
   109  
   110  1. Check out `main`, ensure it's up to date, and ensure you have a clean working directory.
   111  1. Create a new local feature branch from `main`.
   112  1. Update `netlify.toml` to redirect Contour quickstart links to the new release branch.
   113  1. Commit all changes, push the branch, and PR it into `main`.
   114  
   115  ### Do the Github release
   116  
   117  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.
   118  
   119  # Patch Release Process
   120  
   121  ## Overview
   122  
   123  A patch release is e.g. `v1.11.1`.
   124  
   125  A patch release requires:
   126  - patches to be cherry-picked onto the existing release branch
   127  - website updates
   128  - YAML to be customized
   129  - a release tag to be created
   130  - a GitHub release with release notes
   131  - submitting a Gateway API conformance report (if applicable)
   132  - public communication
   133  - cleanup
   134  
   135  ## Process
   136  
   137  ### Set environment variables
   138  
   139  Set environment variables for use in subsequent steps:
   140  
   141  ```bash
   142  export CONTOUR_RELEASE_VERSION=v1.11.1
   143  export CONTOUR_RELEASE_VERSION_MAJOR=1
   144  export CONTOUR_RELEASE_VERSION_MINOR=11
   145  export CONTOUR_PREVIOUS_VERSION=v1.11.0
   146  
   147  export KUBERNETES_MIN_VERSION=1.20
   148  export KUBERNETES_MAX_VERSION=1.22
   149  
   150  export CONTOUR_UPSTREAM_REMOTE_NAME=upstream
   151  ```
   152  
   153  ### Cherry-pick relevant commits into release branch
   154  
   155  1. Get a list of commit SHAs from `main` to backport.
   156  1. 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.
   157  1. Create a new local feature branch from the release branch.
   158  1. Cherry-pick each commit from Step 1, fixing any conflicts as needed:
   159  
   160  ```bash
   161  # repeat for each SHA
   162  git cherry-pick <SHA>
   163  ```
   164  
   165  1. Commit all changes, push the branch, and PR it into the release branch.
   166  
   167  ### Update the website with release-specific information
   168  
   169  1. Check out `main`, ensure it's up to date, and ensure you have a clean working directory.
   170  1. Create a new local feature branch from `main`.
   171  1. Create release notes in `changelogs/CHANGELOG-<version>.md`.
   172  1. Add the new release to the compatibility matrix (`/site/content/resources/compatibility-matrix.md`).
   173  1. Add the new release to the compatibility YAML (`/versions.yaml`).
   174  1. Commit all changes, push the branch, and PR it into `main`.
   175  
   176  ### Update YAML and tag release
   177  
   178  1. Check out the release branch, ensure it's up to date, and ensure you have a clean working directory.
   179  
   180  1. Update the deployment YAML and create a local tag:
   181  
   182  ```bash
   183  ./hack/release/make-release-tag.sh $CONTOUR_PREVIOUS_VERSION $CONTOUR_RELEASE_VERSION
   184  ```
   185  
   186  1. Push the branch to `github.com/projectcontour/contour`:
   187  
   188  ```bash
   189  git push ${CONTOUR_UPSTREAM_REMOTE_NAME} release-${CONTOUR_RELEASE_VERSION_MAJOR}.${CONTOUR_RELEASE_VERSION_MINOR}
   190  ```
   191  
   192  1. Push the tag to `github.com/projectcontour/contour`:
   193  
   194  ```bash
   195  git push ${CONTOUR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}
   196  ```
   197  
   198  ### Submit a Gateway API conformance report
   199  
   200  If the compatible Gateway API version has been bumped in this release, a conformance report should be reported upstream.
   201  Currently the process is manual but we have automated running the conformance suite and report generation in CI on release tags.
   202  Steps to submit a conformance report are:
   203  
   204  1. Find the corresponding `Build and push a release` GitHub Action workflow run for this release from [here][6]
   205  1. Download the `gateway-conformance-report` artifact from the workflow run and unzip
   206  1. Check it for accuracy, and make a PR like [this one][7] to the `gateway-api` repo with the content of the report
   207  
   208  ### Do the Github release
   209  
   210  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.
   211  
   212  # RC Release process
   213  
   214  ## Overview
   215  
   216  An release-candidate release is e.g. `v1.23.0-rc.1`.
   217  
   218  A release-candidate requires:
   219  - a branch off of `main` for the release-candidate
   220  - YAML to be customized
   221  - a release tag to be created
   222  - a GitHub release with release notes
   223  - public communication
   224  - cleanup
   225  
   226  ## Process
   227  
   228  ### Set environment variables
   229  
   230  Set environment variables for use in subsequent steps:
   231  
   232  ```bash
   233  export CONTOUR_RELEASE_VERSION=v1.23.0-rc.1
   234  export CONTOUR_PREVIOUS_VERSION=v1.22.1
   235  
   236  export KUBERNETES_MIN_VERSION=1.23
   237  export KUBERNETES_MAX_VERSION=1.25
   238  
   239  export CONTOUR_UPSTREAM_REMOTE_NAME=upstream
   240  ```
   241  
   242  ### Create a branch for the release
   243  
   244  Typically we will branch off of `main` to cut an RC of an upcoming release and add the release tag on that branch.
   245  This process is easier than managing a `release-*` branch and having to cherry-pick changes over from `main` for additional commits.
   246  
   247  1. Make sure `main` is up to date
   248  1. Create a new local branch from `main` (e.g. `release-1.23.0-rc.1`)
   249  1. Commit all changes, push the branch to `github.com/projectcontour/contour`.
   250  
   251  ### Generate the RC changelog
   252  
   253  1. Ensure the RC branch you created above is clean and up to date.
   254  1. Generate a changelog (the `prepare-release.go` script should detect the version is an RC and only generate a changelog):
   255  
   256      ```bash
   257      go run ./hack/release/prepare-release.go $CONTOUR_RELEASE_VERSION $KUBERNETES_MIN_VERSION $KUBERNETES_MAX_VERSION
   258      ```
   259  1. Proofread the release notes and do any reordering, rewording, reformatting necessary.
   260  1. Commit all changes, push the branch to `github.com/projectcontour/contour`.
   261  
   262  ### Update YAML and tag release
   263  
   264  1. Check out the RC branch, ensure it's up to date, and ensure you have a clean working directory.
   265  
   266  1. Update the deployment YAML and create a local tag:
   267  
   268  ```bash
   269  ./hack/release/make-release-tag.sh $CONTOUR_PREVIOUS_VERSION $CONTOUR_RELEASE_VERSION
   270  ```
   271  
   272  1. Push the branch to `github.com/projectcontour/contour` (e.g. `git push upstream release-1.23.0-rc.1`).
   273  
   274  1. Push the tag to `github.com/projectcontour/contour`:
   275  
   276  ```bash
   277  git push ${CONTOUR_UPSTREAM_REMOTE_NAME} ${CONTOUR_RELEASE_VERSION}
   278  ```
   279  
   280  ### Do the Github release
   281  
   282  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.
   283  
   284  # Release announcements
   285  
   286  After any release, a few communications should be sent out to notify users.
   287  
   288  - Post a note to the #contour channel on k8s slack, also update the /topic with the current release number
   289  - Post a note to the #project-contour channel on the vmware slack, also update the /topic with the current release number
   290  - Send an update to the [cncf-contour-users mailing list][4]
   291  - Send an update to the [cncf-contour-distributors-announce mailing list][5]
   292  - Post a blog entry to projectcontour.io
   293  
   294  # File issues
   295  
   296  If you encountered any problems or areas for improvement while executing the release, file issues before you forget.
   297  
   298  [1]: #minor-release-process
   299  [2]: #patch-release-process
   300  [3]: #rc-release-process
   301  [4]: https://lists.cncf.io/g/cncf-contour-users/
   302  [5]: https://lists.cncf.io/g/cncf-contour-distributors-announce/
   303  [6]: https://github.com/projectcontour/contour/actions/workflows/build_tag.yaml
   304  [7]: https://github.com/kubernetes-sigs/gateway-api/pull/2556