Skip to content

Commit dba39ba

Browse files
RyanTheOptimistRyanTheOptimist
authored
docs: Attempt to flesh out the different release responsibilities (envoyproxy#20851)
Signed-off-by: Ryan Hamilton <[email protected]>
1 parent 1b47eaa commit dba39ba

File tree

2 files changed

+118
-101
lines changed

2 files changed

+118
-101
lines changed

‎GOVERNANCE.md

-77
Original file line numberDiff line numberDiff line change
@@ -68,83 +68,6 @@
6868
[here](https://calendar.google.com/calendar/embed?src=d6glc0l5rc3v235q9l2j29dgovh3dn48%40import.calendar.google.com&ctz=America%2FNew_York)
6969
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)
7070

71-
## Cutting a release
72-
73-
* We do releases every 3 months, as described in the [release schedule](RELEASES.md#release-schedule).
74-
* Take a look at open issues tagged with the current release, by
75-
[searching](https://github.com/envoyproxy/envoy/issues) for
76-
"is:open is:issue milestone:[current milestone]" and either hold off until
77-
they are fixed or bump them to the next milestone.
78-
* Begin marshalling the ongoing PR flow in this repo. Ask maintainers to hold off merging any
79-
particularly risky PRs until after the release is tagged. This is because we aim for main to be
80-
at release candidate quality at all times.
81-
* Do a final check of the [release notes](docs/root/version_history/current.rst):
82-
* Make any needed corrections (grammar, punctuation, formatting, etc.).
83-
* Check to see if any security/stable version release notes are duplicated in
84-
the major version release notes. These should not be duplicated.
85-
* If the "Deprecated" section is empty, delete it.
86-
* Remove the "Pending" tags and add dates to the top of the [release notes for this version](docs/root/version_history/current.rst).
87-
* Switch the [VERSION.txt](VERSION.txt) from a "dev" variant to a final variant. E.g., "1.6.0-dev" to
88-
"1.6.0".
89-
* Update the [RELEASES](RELEASES.md) doc with the relevant dates. Now, or after you cut the
90-
release, please also make sure there's a stable maintainer signed up for next quarter,
91-
and the deadline for the next release is documented in the release schedule.
92-
* Get a review and merge.
93-
* Wait for tests to pass on [main](https://dev.azure.com/cncf/envoy/_build).
94-
* Create a [tagged release](https://github.com/envoyproxy/envoy/releases). The release should
95-
start with "v" and be followed by the version number. E.g., "v1.6.0". **This must match the
96-
[VERSION](VERSION).**
97-
* From the envoy [landing page](https://github.com/envoyproxy/envoy) use the branch drop-down to create a branch
98-
from the tagged release, e.g. "release/v1.6". It will be used for the
99-
[stable releases](RELEASES.md#stable-releases).
100-
* Tagging will kick off another run of [AZP postsubmit](https://dev.azure.com/cncf/envoy/_build?definitionId=11). Monitor that
101-
tag build to make sure that the final docker images get pushed along with
102-
the final docs. The final documentation will end up in the
103-
[envoy-website repository](https://github.com/envoyproxy/envoy-website/tree/main/docs/envoy).
104-
* Update the website ([example PR](https://github.com/envoyproxy/envoy-website/pull/148)) for the new release.
105-
* Craft a witty/uplifting email and send it to all the email aliases including envoy-announce@.
106-
* Make sure we tweet the new release: either have Matt do it or email [email protected] and ask them to do an Envoy account
107-
post.
108-
* Do a new PR to setup the next version
109-
* Update [VERSION.txt](VERSION.txt) to the next development release. E.g., "1.7.0-dev".
110-
* `git mv docs/root/version_history/current.rst docs/root/version_history/v1.6.0.rst`, filling in the previous
111-
release version number in the filename and delete empty sections (like Incompatible Behavior Changes, Minor Bahavior Changes, etc).
112-
Add an entry for the new file in the `toctree` in
113-
[version_history.rst](docs/root/version_history/version_history.rst).
114-
* Create a new "current" version history file at the [release
115-
notes](docs/root/version_history/current.rst) for the following version. E.g., "1.7.0 (pending)". Use
116-
this text as the template for the new file:
117-
```
118-
1.7.0 (Pending)
119-
===============
120-
121-
Incompatible Behavior Changes
122-
-----------------------------
123-
*Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required*
124-
125-
Minor Behavior Changes
126-
----------------------
127-
*Changes that may cause incompatibilities for some users, but should not for most*
128-
129-
Bug Fixes
130-
---------
131-
*Changes expected to improve the state of the world and are unlikely to have negative effects*
132-
133-
Removed Config or Runtime
134-
-------------------------
135-
*Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
136-
137-
New Features
138-
------------
139-
140-
Deprecated
141-
----------
142-
```
143-
* Run the deprecate_versions.py script (e.g. `bazel run //tools/deprecate_version:deprecate_version`)
144-
to file tracking issues for runtime guarded code which can be removed.
145-
* Check source/common/runtime/runtime_features.cc and see if any runtime guards in
146-
disabled_runtime_features should be reassessed, and ping on the relevant issues.
147-
14871
## When does a maintainer lose maintainer status
14972

15073
If a maintainer is no longer interested or cannot perform the maintainer duties listed above, they

‎RELEASES.md

+118-24
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,17 @@ Active development is happening on the `main` branch, and a new version is relea
88

99
Stable releases of Envoy include:
1010

11-
* Extended maintenance window (any version released in the last 12 months).
12-
* Security fixes backported from the `main` branch (including those deemed not worthy
13-
of creating a CVE).
14-
* Stability fixes backported from the `main` branch (anything that can result in a crash,
15-
including crashes triggered by a trusted control plane).
16-
* Bugfixes, deemed worthwhile by the maintainers of stable releases.
11+
* Major releases in which a new version a created directly from the `main` branch.
12+
* Minor releases for versions covered by the extended maintenance window (any version released in the last 12 months).
13+
* Security fixes backported from the `main` branch (including those deemed not worthy
14+
of creating a CVE).
15+
* Stability fixes backported from the `main` branch (anything that can result in a crash,
16+
including crashes triggered by a trusted control plane).
17+
* Bugfixes, deemed worthwhile by the maintainers of stable releases.
18+
19+
Major releases happen quartely and follow the schedule below. Security fixes typically happen
20+
quarterly as well, but this depends on the number and severity of security bugs. Other releases
21+
are ad-hoc and best-effort.
1722

1823
### Hand-off
1924

@@ -42,23 +47,30 @@ schedule, initially aiming for the bi-weekly releases.
4247

4348
### Release management
4449

45-
Release managers of stable releases are responsible for approving and merging backports, tagging
46-
stable releases and sending announcements about them. This role is rotating on a quarterly basis.
47-
48-
| Quarter | Release manager |
49-
|:-------:|:--------------------------------------------------------------:|
50-
| 2020 Q1 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) |
51-
| 2020 Q2 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) |
52-
| 2020 Q3 | Yuchen Dai ([lambdai](https://github.com/lambdai)) |
53-
| 2020 Q4 | Christoph Pakulski ([cpakulski](https://github.com/cpakulski)) |
54-
| 2021 Q1 | Rei Shimizu ([Shikugawa](https://github.com/Shikugawa)) |
55-
| 2021 Q2 | Dmitri Dolguikh ([dmitri-d](https://github.com/dmitri-d)) |
56-
| 2021 Q3 | Takeshi Yoneda ([mathetake](https://github.com/mathetake)) |
57-
| 2021 Q4 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) |
58-
| 2022 Q1 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) |
59-
| 2022 Q2 | Pradeep Rao ([pradeepcrao](https://github.com/pradeepcrao)) |
60-
61-
## Release schedule
50+
Major releases are handled by the maintainer on-call and do not involve any backports.
51+
The details are outlined in the "Cutting a major release" section below.
52+
Security releases are handled by a Release Manager and a Fix Lead. The Release Manager is
53+
responsible for approving and merging backports, with responsibilties outlined
54+
[in this doc](https://docs.google.com/document/d/1AnIqmJlGlN0nZaxDme2uMjcO9VJxIokGDMYsq2IZM98/edit).
55+
The Fix Lead is a member of the security
56+
team and is responsible for coordinating the overall release. This includes identifying
57+
issues to be fixed in the release, communications with the Envoy community, and the
58+
actual mechanics of the release itself.
59+
60+
| Quarter | Release Manager | Fix Lead |
61+
|:-------:|:--------------------------------------------------------------:|:----------------------------------------------------------------------|
62+
| 2020 Q1 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) | |
63+
| 2020 Q2 | Piotr Sikora ([PiotrSikora](https://github.com/PiotrSikora)) | |
64+
| 2020 Q3 | Yuchen Dai ([lambdai](https://github.com/lambdai)) | |
65+
| 2020 Q4 | Christoph Pakulski ([cpakulski](https://github.com/cpakulski)) | |
66+
| 2021 Q1 | Rei Shimizu ([Shikugawa](https://github.com/Shikugawa)) | |
67+
| 2021 Q2 | Dmitri Dolguikh ([dmitri-d](https://github.com/dmitri-d)) | |
68+
| 2021 Q3 | Takeshi Yoneda ([mathetake](https://github.com/mathetake)) | |
69+
| 2021 Q4 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | |
70+
| 2022 Q1 | Otto van der Schaaf ([oschaaf](https://github.com/oschaaf)) | Ryan Hamilton ([RyanTheOptimist](https://github.com/RyanTheOptimist)) |
71+
| 2022 Q2 | Pradeep Rao ([pradeepcrao](https://github.com/pradeepcrao)) | TBD |
72+
73+
## Major release schedule
6274

6375
In order to accommodate downstream projects, new Envoy releases are produced on a fixed release
6476
schedule (the 15th day of each quarter), with an acceptable delay of up to 2 weeks, with a hard
@@ -79,4 +91,86 @@ deadline of 3 weeks.
7991
| 1.22.0 | 2022/04/15 | 2022/04/15 | 0 days | 2023/04/15 |
8092
| 1.23.0 | 2022/07/15 | | | |
8193

82-
[repokitteh]: https://github.com/repokitteh
94+
### Cutting a major release
95+
96+
* Take a look at open issues tagged with the current release, by
97+
[searching](https://github.com/envoyproxy/envoy/issues) for
98+
"is:open is:issue milestone:[current milestone]" and either hold off until
99+
they are fixed or bump them to the next milestone.
100+
* Begin marshalling the ongoing PR flow in this repo. Ask maintainers to hold off merging any
101+
particularly risky PRs until after the release is tagged. This is because we aim for main to be
102+
at release candidate quality at all times.
103+
* Do a final check of the [release notes](docs/root/version_history/current.rst):
104+
* Make any needed corrections (grammar, punctuation, formatting, etc.).
105+
* Check to see if any security/stable version release notes are duplicated in
106+
the major version release notes. These should not be duplicated.
107+
* If the "Deprecated" section is empty, delete it.
108+
* Remove the "Pending" tags and add dates to the top of the [release notes for this version](docs/root/version_history/current.rst).
109+
* Switch the [VERSION.txt](VERSION.txt) from a "dev" variant to a final variant. E.g., "1.6.0-dev" to
110+
"1.6.0".
111+
* Update the [RELEASES](RELEASES.md) doc with the relevant dates. Now, or after you cut the
112+
release, please also make sure there's a stable maintainer signed up for next quarter,
113+
and the deadline for the next release is documented in the release schedule.
114+
* Get a review and merge.
115+
* Wait for tests to pass on [main](https://dev.azure.com/cncf/envoy/_build).
116+
* Create a [tagged release](https://github.com/envoyproxy/envoy/releases). The release should
117+
start with "v" and be followed by the version number. E.g., "v1.6.0". **This must match the
118+
[VERSION](VERSION).**
119+
* From the envoy [landing page](https://github.com/envoyproxy/envoy) use the branch drop-down to create a branch
120+
from the tagged release, e.g. "release/v1.6". It will be used for the
121+
[stable releases](RELEASES.md#stable-releases).
122+
* Tagging will kick off another run of [AZP postsubmit](https://dev.azure.com/cncf/envoy/_build?definitionId=11). Monitor that
123+
tag build to make sure that the final docker images get pushed along with
124+
the final docs. The final documentation will end up in the
125+
[envoy-website repository](https://github.com/envoyproxy/envoy-website/tree/main/docs/envoy).
126+
* Update the website ([example PR](https://github.com/envoyproxy/envoy-website/pull/148)) for the new release.
127+
* Craft a witty/uplifting email and send it to all the email aliases including envoy-announce@.
128+
* Make sure we tweet the new release: either have Matt do it or email [email protected] and ask them to do an Envoy account
129+
post.
130+
* Do a new PR to setup the next version
131+
* Update [VERSION.txt](VERSION.txt) to the next development release. E.g., "1.7.0-dev".
132+
* `git mv docs/root/version_history/current.rst docs/root/version_history/v1.6.0.rst`, filling in the previous
133+
release version number in the filename and delete empty sections (like Incompatible Behavior Changes, Minor Bahavior Changes, etc).
134+
Add an entry for the new file in the `toctree` in
135+
[version_history.rst](docs/root/version_history/version_history.rst).
136+
* 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 <actual link>` `` -> `` :ref:`Some link text <v1.16:actual link>` ``
137+
* Create a new "current" version history file at the [release
138+
notes](docs/root/version_history/current.rst) for the following version. E.g., "1.7.0 (pending)". Use
139+
this text as the template for the new file:
140+
```
141+
1.7.0 (Pending)
142+
===============
143+
144+
Incompatible Behavior Changes
145+
-----------------------------
146+
*Changes that are expected to cause an incompatibility if applicable; deployment changes are likely required*
147+
148+
Minor Behavior Changes
149+
----------------------
150+
*Changes that may cause incompatibilities for some users, but should not for most*
151+
152+
Bug Fixes
153+
---------
154+
*Changes expected to improve the state of the world and are unlikely to have negative effects*
155+
156+
Removed Config or Runtime
157+
-------------------------
158+
*Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
159+
160+
New Features
161+
------------
162+
163+
Deprecated
164+
----------
165+
```
166+
* Run the deprecate_versions.py script (e.g. `bazel run //tools/deprecate_version:deprecate_version`)
167+
to file tracking issues for runtime guarded code which can be removed.
168+
* Check source/common/runtime/runtime_features.cc and see if any runtime guards in
169+
disabled_runtime_features should be reassessed, and ping on the relevant issues.
170+
171+
172+
## Security release schedule
173+
174+
There is no fixed scheduled for security fixes. Zero-day vulnerabilities might necessitate
175+
an emergency release with little or no warning. However, historically security release have
176+
happened roughly once per quarter, midway between major releases.

0 commit comments

Comments
 (0)