From 71a5d41674814e5cc287f68c00bffc1d1e3734ad Mon Sep 17 00:00:00 2001 From: Ryan Hamilton Date: Fri, 15 Apr 2022 17:39:11 +0000 Subject: [PATCH 1/6] docs: Attempt to flesh out the different release responsibilities Signed-off-by: Ryan Hamilton --- RELEASES.md | 52 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index 7a09e6576ffe..326be6a67db8 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -8,6 +8,11 @@ Active development is happening on the `main` branch, and a new version is relea Stable releases of Envoy include: +TODO(RyanTheOptimist): It seems to me that we have two kinds of releases and it would be helpful for +this doc to make a clear distinction between them. For the sake of argument, I've called them +"Major Release" (v1.22) and "Security Releases" (v1.22.1, etc). Does this terminology work? + +* Major releases in which a new version a created directly from the `main` branch. * Extended maintenance window (any version released in the last 12 months). * Security fixes backported from the `main` branch (including those deemed not worthy of creating a CVE). @@ -22,11 +27,12 @@ version from the `main` branch by creating a `vX.Y.0` tag and a corresponding `r branch, with merge permissions given to the release manager of stable releases, and CI configured to execute tests on it. -### Security releases +### Security Releases Critical security fixes are owned by the Envoy security team, which provides fixes for the `main` branch. Once those fixes are ready, the maintainers of stable releases backport them to the remaining supported stable releases. +TODO(RyanTheOptimist): Should this perhaps mention that this process is not "in-the-clear"? ### Backports @@ -40,25 +46,30 @@ are backported from the `main` branch to all supported stable branches by the ma stable releases. New stable versions from non-critical security fixes are released on a regular schedule, initially aiming for the bi-weekly releases. -### Release management - -Release managers of stable releases are responsible for approving and merging backports, tagging -stable releases and sending announcements about them. This role is rotating on a quarterly basis. - -| Quarter | Release manager | -|:-------:|:--------------------------------------------------------------:| -| 2020 Q1 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) | -| 2020 Q2 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) | -| 2020 Q3 | Yuchen Dai ([lambdai](https://github.com/lambdai)) | -| 2020 Q4 | Christoph Pakulski ([cpakulski](https://github.com/cpakulski)) | -| 2021 Q1 | Rei Shimizu ([Shikugawa](https://github.com/Shikugawa)) | -| 2021 Q2 | Dmitri Dolguikh ([dmitri-d](https://github.com/dmitri-d)) | -| 2021 Q3 | Takeshi Yoneda ([mathetake](https://github.com/mathetake)) | -| 2021 Q4 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | -| 2022 Q1 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | -| 2022 Q2 | Pradeep Rao ([pradeepcrao](https://github.com/pradeepcrao)) | - -## Release schedule +### Release Management + +Major releases are handled by Matt Klein ([mattklein123](https://github.com/mattklein123)) +or Alyssa Wilk ([alyssawilk](https://github.com/alyssawilk)) and do not involve any backports. +Security releases are handled by a Release Manager and a Fix Lead. The Release Manager is +responsible for approving and merging backports. The Fix Lead is a member of the security +team and is responsible for coordinating the overall release. This includes identifying +issues to be fixed in the release, communications with the Envoy community, and the +actual mechanics of the release itself. + +| Quarter | Release Manager | Fix Lead | +|:-------:|:--------------------------------------------------------------:|:----------------------------------------------------------------------| +| 2020 Q1 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) | | +| 2020 Q2 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) | | +| 2020 Q3 | Yuchen Dai ([lambdai](https://github.com/lambdai)) | | +| 2020 Q4 | Christoph Pakulski ([cpakulski](https://github.com/cpakulski)) | | +| 2021 Q1 | Rei Shimizu ([Shikugawa](https://github.com/Shikugawa)) | | +| 2021 Q2 | Dmitri Dolguikh ([dmitri-d](https://github.com/dmitri-d)) | | +| 2021 Q3 | Takeshi Yoneda ([mathetake](https://github.com/mathetake)) | | +| 2021 Q4 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | | +| 2022 Q1 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | Ryan Hamilton ([RyanTheOptimist](https://github.com/RyanTheOptimist)) | +| 2022 Q2 | Pradeep Rao ([pradeepcrao](https://github.com/pradeepcrao)) | TBD | + +## Major Release Schedule In order to accommodate downstream projects, new Envoy releases are produced on a fixed release schedule (the 15th day of each quarter), with an acceptable delay of up to 2 weeks, with a hard @@ -79,4 +90,5 @@ deadline of 3 weeks. | 1.22.0 | 2022/04/15 | 2022/04/15 | 0 days | 2023/04/15 | | 1.23.0 | 2022/07/15 | | | | +TODO(RyanTheOptimist): Should we also mention the security release schedule here? I think that would be helpful. [repokitteh]: https://github.com/repokitteh From 257b3a337466f0629734e6e8a31d048adc1f8891 Mon Sep 17 00:00:00 2001 From: Ryan Hamilton Date: Fri, 15 Apr 2022 17:51:46 +0000 Subject: [PATCH 2/6] Reference GOVERNANCE.md Signed-off-by: Ryan Hamilton --- RELEASES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASES.md b/RELEASES.md index 326be6a67db8..7a4e41f2904b 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -50,6 +50,7 @@ schedule, initially aiming for the bi-weekly releases. Major releases are handled by Matt Klein ([mattklein123](https://github.com/mattklein123)) or Alyssa Wilk ([alyssawilk](https://github.com/alyssawilk)) and do not involve any backports. +The details are outlined in the "Cutting a release" section of [GOVERNANCE.md](GOVERNANCE.md). Security releases are handled by a Release Manager and a Fix Lead. The Release Manager is responsible for approving and merging backports. The Fix Lead is a member of the security team and is responsible for coordinating the overall release. This includes identifying From a887c45c994d0fe75a3d94976480b4055aec776f Mon Sep 17 00:00:00 2001 From: Ryan Hamilton Date: Mon, 18 Apr 2022 23:10:54 +0000 Subject: [PATCH 3/6] Address comments Signed-off-by: Ryan Hamilton --- RELEASES.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index 7a4e41f2904b..6f7df9df5722 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -27,7 +27,7 @@ version from the `main` branch by creating a `vX.Y.0` tag and a corresponding `r branch, with merge permissions given to the release manager of stable releases, and CI configured to execute tests on it. -### Security Releases +### Security releases Critical security fixes are owned by the Envoy security team, which provides fixes for the `main` branch. Once those fixes are ready, the maintainers @@ -46,7 +46,7 @@ are backported from the `main` branch to all supported stable branches by the ma stable releases. New stable versions from non-critical security fixes are released on a regular schedule, initially aiming for the bi-weekly releases. -### Release Management +### Release management Major releases are handled by Matt Klein ([mattklein123](https://github.com/mattklein123)) or Alyssa Wilk ([alyssawilk](https://github.com/alyssawilk)) and do not involve any backports. @@ -70,7 +70,7 @@ actual mechanics of the release itself. | 2022 Q1 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | Ryan Hamilton ([RyanTheOptimist](https://github.com/RyanTheOptimist)) | | 2022 Q2 | Pradeep Rao ([pradeepcrao](https://github.com/pradeepcrao)) | TBD | -## Major Release Schedule +## Major release schedule In order to accommodate downstream projects, new Envoy releases are produced on a fixed release schedule (the 15th day of each quarter), with an acceptable delay of up to 2 weeks, with a hard @@ -91,5 +91,8 @@ deadline of 3 weeks. | 1.22.0 | 2022/04/15 | 2022/04/15 | 0 days | 2023/04/15 | | 1.23.0 | 2022/07/15 | | | | -TODO(RyanTheOptimist): Should we also mention the security release schedule here? I think that would be helpful. -[repokitteh]: https://github.com/repokitteh +## Security release schedule + +There is no fixed scheduled for security fixes. Zero-day vulnerabilities might necessitate +an emergency release with little or no warning. However, historically security release have +happened roughly once per quarter, midway between major releases. From 32aeb5191c24c63963410c3c3dec11e566f2e773 Mon Sep 17 00:00:00 2001 From: Ryan Hamilton Date: Mon, 25 Apr 2022 21:05:30 +0000 Subject: [PATCH 4/6] Move stable release process from GOVERNANCE.md to RELEASES.md Signed-off-by: Ryan Hamilton --- GOVERNANCE.md | 77 ------------------------------------- RELEASES.md | 102 +++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 88 insertions(+), 91 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index edc29eecb9de..743edda8c4c6 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -68,83 +68,6 @@ [here](https://calendar.google.com/calendar/embed?src=d6glc0l5rc3v235q9l2j29dgovh3dn48%40import.calendar.google.com&ctz=America%2FNew_York) or you can subscribe to the iCal feed [here](webcal://kubernetes.app.opsgenie.com/webapi/webcal/getRecentSchedule?webcalToken=39dd1a892faa8d0d689f889b9d09ae787355ddff894396546726a5a02bac5b26&scheduleId=a3505963-c064-4c97-8865-947dfcb06060) -## Cutting a release - -* We do releases every 3 months, as described in the [release schedule](RELEASES.md#release-schedule). -* Take a look at open issues tagged with the current release, by - [searching](https://github.com/envoyproxy/envoy/issues) for - "is:open is:issue milestone:[current milestone]" and either hold off until - they are fixed or bump them to the next milestone. -* Begin marshalling the ongoing PR flow in this repo. Ask maintainers to hold off merging any - particularly risky PRs until after the release is tagged. This is because we aim for main to be - at release candidate quality at all times. -* Do a final check of the [release notes](docs/root/version_history/current.rst): - * Make any needed corrections (grammar, punctuation, formatting, etc.). - * Check to see if any security/stable version release notes are duplicated in - the major version release notes. These should not be duplicated. - * If the "Deprecated" section is empty, delete it. - * Remove the "Pending" tags and add dates to the top of the [release notes for this version](docs/root/version_history/current.rst). - * Switch the [VERSION.txt](VERSION.txt) from a "dev" variant to a final variant. E.g., "1.6.0-dev" to - "1.6.0". - * Update the [RELEASES](RELEASES.md) doc with the relevant dates. Now, or after you cut the - release, please also make sure there's a stable maintainer signed up for next quarter, - and the deadline for the next release is documented in the release schedule. - * Get a review and merge. -* Wait for tests to pass on [main](https://dev.azure.com/cncf/envoy/_build). -* Create a [tagged release](https://github.com/envoyproxy/envoy/releases). The release should - start with "v" and be followed by the version number. E.g., "v1.6.0". **This must match the - [VERSION](VERSION).** -* From the envoy [landing page](https://github.com/envoyproxy/envoy) use the branch drop-down to create a branch - from the tagged release, e.g. "release/v1.6". It will be used for the - [stable releases](RELEASES.md#stable-releases). -* Tagging will kick off another run of [AZP postsubmit](https://dev.azure.com/cncf/envoy/_build?definitionId=11). Monitor that - tag build to make sure that the final docker images get pushed along with - the final docs. The final documentation will end up in the - [envoyproxy.github.io repository](https://github.com/envoyproxy/envoyproxy.github.io/tree/main/docs/envoy). -* Update the website ([example PR](https://github.com/envoyproxy/envoyproxy.github.io/pull/148)) for the new release. -* Craft a witty/uplifting email and send it to all the email aliases including envoy-announce@. -* Make sure we tweet the new release: either have Matt do it or email social@cncf.io and ask them to do an Envoy account - post. -* Do a new PR to setup the next version - * Update [VERSION.txt](VERSION.txt) to the next development release. E.g., "1.7.0-dev". - * `git mv docs/root/version_history/current.rst docs/root/version_history/v1.6.0.rst`, filling in the previous - release version number in the filename and delete empty sections (like Incompatible Behavior Changes, Minor Bahavior Changes, etc). - Add an entry for the new file in the `toctree` in - [version_history.rst](docs/root/version_history/version_history.rst). - * Create a new "current" version history file at the [release - notes](docs/root/version_history/current.rst) for the following version. E.g., "1.7.0 (pending)". Use - this text as the template for the new file: -``` -1.7.0 (Pending) -=============== - -Incompatible Behavior Changes ------------------------------ -*Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required* - -Minor Behavior Changes ----------------------- -*Changes that may cause incompatibilities for some users, but should not for most* - -Bug Fixes ---------- -*Changes expected to improve the state of the world and are unlikely to have negative effects* - -Removed Config or Runtime -------------------------- -*Normally occurs at the end of the* :ref:`deprecation period ` - -New Features ------------- - -Deprecated ----------- -``` -* Run the deprecate_versions.py script (e.g. `bazel run //tools/deprecate_version:deprecate_version`) - to file tracking issues for runtime guarded code which can be removed. -* Check source/common/runtime/runtime_features.cc and see if any runtime guards in - disabled_runtime_features should be reassessed, and ping on the relevant issues. - ## When does a maintainer lose maintainer status If a maintainer is no longer interested or cannot perform the maintainer duties listed above, they diff --git a/RELEASES.md b/RELEASES.md index 6f7df9df5722..9191582d9dee 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -8,17 +8,16 @@ Active development is happening on the `main` branch, and a new version is relea Stable releases of Envoy include: -TODO(RyanTheOptimist): It seems to me that we have two kinds of releases and it would be helpful for -this doc to make a clear distinction between them. For the sake of argument, I've called them -"Major Release" (v1.22) and "Security Releases" (v1.22.1, etc). Does this terminology work? - * Major releases in which a new version a created directly from the `main` branch. -* Extended maintenance window (any version released in the last 12 months). -* Security fixes backported from the `main` branch (including those deemed not worthy - of creating a CVE). -* Stability fixes backported from the `main` branch (anything that can result in a crash, - including crashes triggered by a trusted control plane). -* Bugfixes, deemed worthwhile by the maintainers of stable releases. +* Minor releases for versions covered by the extended maintenance window (any version released in the last 12 months). + * Security fixes backported from the `main` branch (including those deemed not worthy + of creating a CVE). + * Stability fixes backported from the `main` branch (anything that can result in a crash, + including crashes triggered by a trusted control plane). + * Bugfixes, deemed worthwhile by the maintainers of stable releases. + +Major release and security fixes both happen quartely whereas other releases are ad-hoc and +best-effort. ### Hand-off @@ -32,7 +31,6 @@ to execute tests on it. Critical security fixes are owned by the Envoy security team, which provides fixes for the `main` branch. Once those fixes are ready, the maintainers of stable releases backport them to the remaining supported stable releases. -TODO(RyanTheOptimist): Should this perhaps mention that this process is not "in-the-clear"? ### Backports @@ -48,9 +46,8 @@ schedule, initially aiming for the bi-weekly releases. ### Release management -Major releases are handled by Matt Klein ([mattklein123](https://github.com/mattklein123)) -or Alyssa Wilk ([alyssawilk](https://github.com/alyssawilk)) and do not involve any backports. -The details are outlined in the "Cutting a release" section of [GOVERNANCE.md](GOVERNANCE.md). +Major releases are handled by the maintainer on-call and do not involve any backports. +The details are outlined in the "Cutting a major release" section below. Security releases are handled by a Release Manager and a Fix Lead. The Release Manager is responsible for approving and merging backports. The Fix Lead is a member of the security team and is responsible for coordinating the overall release. This includes identifying @@ -91,6 +88,83 @@ deadline of 3 weeks. | 1.22.0 | 2022/04/15 | 2022/04/15 | 0 days | 2023/04/15 | | 1.23.0 | 2022/07/15 | | | | +### Cutting a major release + +* Take a look at open issues tagged with the current release, by + [searching](https://github.com/envoyproxy/envoy/issues) for + "is:open is:issue milestone:[current milestone]" and either hold off until + they are fixed or bump them to the next milestone. +* Begin marshalling the ongoing PR flow in this repo. Ask maintainers to hold off merging any + particularly risky PRs until after the release is tagged. This is because we aim for main to be + at release candidate quality at all times. +* Do a final check of the [release notes](docs/root/version_history/current.rst): + * Make any needed corrections (grammar, punctuation, formatting, etc.). + * Check to see if any security/stable version release notes are duplicated in + the major version release notes. These should not be duplicated. + * If the "Deprecated" section is empty, delete it. + * Remove the "Pending" tags and add dates to the top of the [release notes for this version](docs/root/version_history/current.rst). + * Switch the [VERSION.txt](VERSION.txt) from a "dev" variant to a final variant. E.g., "1.6.0-dev" to + "1.6.0". + * Update the [RELEASES](RELEASES.md) doc with the relevant dates. Now, or after you cut the + release, please also make sure there's a stable maintainer signed up for next quarter, + and the deadline for the next release is documented in the release schedule. + * Get a review and merge. +* Wait for tests to pass on [main](https://dev.azure.com/cncf/envoy/_build). +* Create a [tagged release](https://github.com/envoyproxy/envoy/releases). The release should + start with "v" and be followed by the version number. E.g., "v1.6.0". **This must match the + [VERSION](VERSION).** +* From the envoy [landing page](https://github.com/envoyproxy/envoy) use the branch drop-down to create a branch + from the tagged release, e.g. "release/v1.6". It will be used for the + [stable releases](RELEASES.md#stable-releases). +* Tagging will kick off another run of [AZP postsubmit](https://dev.azure.com/cncf/envoy/_build?definitionId=11). Monitor that + tag build to make sure that the final docker images get pushed along with + the final docs. The final documentation will end up in the + [envoyproxy.github.io repository](https://github.com/envoyproxy/envoyproxy.github.io/tree/main/docs/envoy). +* Update the website ([example PR](https://github.com/envoyproxy/envoyproxy.github.io/pull/148)) for the new release. +* Craft a witty/uplifting email and send it to all the email aliases including envoy-announce@. +* Make sure we tweet the new release: either have Matt do it or email social@cncf.io and ask them to do an Envoy account + post. +* Do a new PR to setup the next version + * Update [VERSION.txt](VERSION.txt) to the next development release. E.g., "1.7.0-dev". + * `git mv docs/root/version_history/current.rst docs/root/version_history/v1.6.0.rst`, filling in the previous + release version number in the filename and delete empty sections (like Incompatible Behavior Changes, Minor Bahavior Changes, etc). + Add an entry for the new file in the `toctree` in + [version_history.rst](docs/root/version_history/version_history.rst). + * Create a new "current" version history file at the [release + notes](docs/root/version_history/current.rst) for the following version. E.g., "1.7.0 (pending)". Use + this text as the template for the new file: +``` +1.7.0 (Pending) +=============== + +Incompatible Behavior Changes +----------------------------- +*Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required* + +Minor Behavior Changes +---------------------- +*Changes that may cause incompatibilities for some users, but should not for most* + +Bug Fixes +--------- +*Changes expected to improve the state of the world and are unlikely to have negative effects* + +Removed Config or Runtime +------------------------- +*Normally occurs at the end of the* :ref:`deprecation period ` + +New Features +------------ + +Deprecated +---------- +``` +* Run the deprecate_versions.py script (e.g. `bazel run //tools/deprecate_version:deprecate_version`) + to file tracking issues for runtime guarded code which can be removed. +* Check source/common/runtime/runtime_features.cc and see if any runtime guards in + disabled_runtime_features should be reassessed, and ping on the relevant issues. + + ## Security release schedule There is no fixed scheduled for security fixes. Zero-day vulnerabilities might necessitate From 58837c97d71acb1139857c8fa2e016af79263f5c Mon Sep 17 00:00:00 2001 From: Ryan Hamilton Date: Tue, 26 Apr 2022 17:52:41 +0000 Subject: [PATCH 5/6] Address comments Signed-off-by: Ryan Hamilton --- RELEASES.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index 2acbe294f75f..9dc5c5adda17 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -16,8 +16,9 @@ Stable releases of Envoy include: including crashes triggered by a trusted control plane). * Bugfixes, deemed worthwhile by the maintainers of stable releases. -Major release and security fixes both happen quartely whereas other releases are ad-hoc and -best-effort. +Major releases happen quartely and follow the schedule below. Security fixes typically happen +quarterly as well, but this depends on the number and severity of security bugs. Other releases +are ad-hoc and best-effort. ### Hand-off @@ -49,7 +50,9 @@ schedule, initially aiming for the bi-weekly releases. Major releases are handled by the maintainer on-call and do not involve any backports. The details are outlined in the "Cutting a major release" section below. Security releases are handled by a Release Manager and a Fix Lead. The Release Manager is -responsible for approving and merging backports. The Fix Lead is a member of the security +responsible for approving and merging backports, with responsibilties outlined +[in this doc](https://docs.google.com/document/d/1AnIqmJlGlN0nZaxDme2uMjcO9VJxIokGDMYsq2IZM98/edit). +The Fix Lead is a member of the security team and is responsible for coordinating the overall release. This includes identifying issues to be fixed in the release, communications with the Envoy community, and the actual mechanics of the release itself. From 1db0a72984e406dca6d7f8db029272f6d47903a0 Mon Sep 17 00:00:00 2001 From: Ryan Hamilton Date: Tue, 26 Apr 2022 18:02:14 +0000 Subject: [PATCH 6/6] New version steps Signed-off-by: Ryan Hamilton --- RELEASES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASES.md b/RELEASES.md index 9dc5c5adda17..a0a6edb3832e 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -133,6 +133,7 @@ deadline of 3 weeks. release version number in the filename and delete empty sections (like Incompatible Behavior Changes, Minor Bahavior Changes, etc). Add an entry for the new file in the `toctree` in [version_history.rst](docs/root/version_history/version_history.rst). + * Edit the file you just created (eg `docs/root/version_history/v1.6.0.rst`) replacing the link part (between the `<>`) of any `ref:` links to point at the version - eg `` :ref:`Some link text ` `` -> `` :ref:`Some link text ` `` * Create a new "current" version history file at the [release notes](docs/root/version_history/current.rst) for the following version. E.g., "1.7.0 (pending)". Use this text as the template for the new file: