-
Notifications
You must be signed in to change notification settings - Fork 4.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Attempt to flesh out the different release responsibilities #20851
Changes from 6 commits
71a5d41
257b3a3
a887c45
32aeb51
34f3d3f
58837c9
1db0a72
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
[envoy-website repository](https://github.com/envoyproxy/envoy-website/tree/main/docs/envoy). | ||
* Update the website ([example PR](https://github.com/envoyproxy/envoy-website/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 [email protected] 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 <deprecated>` | ||
|
||
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 | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -8,12 +8,17 @@ Active development is happening on the `main` branch, and a new version is relea | |
|
||
Stable releases of Envoy include: | ||
|
||
* 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 releases in which a new version a created directly from the `main` branch. | ||
* 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 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 | ||
|
||
|
@@ -42,23 +47,30 @@ 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 | ||
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, 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. | ||
alyssawilk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
| 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 +91,85 @@ deadline of 3 weeks. | |
| 1.22.0 | 2022/04/15 | 2022/04/15 | 0 days | 2023/04/15 | | ||
| 1.23.0 | 2022/07/15 | | | | | ||
|
||
[repokitteh]: https://github.com/repokitteh | ||
### 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): | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. no - not here - this branch wants to keep links to its own version - we only update the in the case of a release from this is because to use a concrete example - at the point of just happened
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @phlax Can you suggest text to be added here? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. i think the text here is fine - its below that we need to update.... |
||
* 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 | ||
[envoy-website repository](https://github.com/envoyproxy/envoy-website/tree/main/docs/envoy). | ||
* Update the website ([example PR](https://github.com/envoyproxy/envoy-website/pull/148)) for the new release. | ||
phlax marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. lets just remove this - its not quite correct, and is about to be obsolete There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done! |
||
* 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 [email protected] 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". | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. * Edit `docs/conf.py` adding a version to `intersphinx_mapping`, eg:
\```python
'v1.16': ('https://www.envoyproxy.io/docs/envoy/v1.16.0', None),
\```
this should work for now - there is another step required to sync inventories and use a local copy - but some missing railway track for that There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. lets not worry about this for now and i will either try to automate or add relevant docs if we dont resolve this, it will cause issues down the road, and has mostly been forgotten, so ill try to prioritize automating this update, or making it unnecessary |
||
* `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). | ||
phlax marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* 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 <deprecated>` | ||
|
||
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 | ||
an emergency release with little or no warning. However, historically security release have | ||
happened roughly once per quarter, midway between major releases. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do we want to link to the docs here? is there anything private in the doc?
AFIK the release manager generally responsible for doing backports for releases.
Also somewhere maybe we should outline all the responsibilities for the role? Right now they're docced up here https://docs.google.com/document/d/1AnIqmJlGlN0nZaxDme2uMjcO9VJxIokGDMYsq2IZM98/edit but we could fold the content in here and delete that doc?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, I didn't realize that doc existed. I added a link to it. But I'd be happy to inline it here, if you think that would be better?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah I think inlining would be better but you're already voluntering for enough improvements so your call :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will do! But I'll do it in a follow up so as not to drag this PR out any longer.