Active development is happening on the main branch, and a new version is released from it.
Stable releases of Envoy include:
- Major releases in which a new version a created directly from the
mainbranch. - Minor releases for versions covered by the extended maintenance window (any version released in the last 12 months).
- Security fixes backported from the
mainbranch (including those deemed not worthy of creating a CVE). - Stability fixes backported from the
mainbranch (anything that can result in a crash, including crashes triggered by a trusted control plane). - Bugfixes, deemed worthwhile by the maintainers of stable releases.
- Security fixes backported from the
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 to the maintainers of stable releases happens after Envoy maintainers release a new
version from the main branch by creating a vX.Y.0 tag and a corresponding release/vX.Y
branch, with merge permissions given to the release manager of stable releases, and CI configured
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.
All other security and reliability fixes can be nominated for backporting to stable releases
by Envoy maintainers, Envoy security team, the change author, or members of the Envoy community
by adding the backport/review or backport/approved label (this can be done using [repokitteh]'s
/backport command). Changes nominated by the change author and/or members of the Envoy community
are evaluated for backporting on a case-by-case basis, and require approval from either the release
manager of stable release, Envoy maintainers, or Envoy security team. Once approved, those fixes
are backported from the main branch to all supported stable branches by the maintainers of
stable releases. New stable versions from non-critical security fixes are released on a regular
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, with responsibilties outlined in this doc. 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) | |
| 2020 Q2 | Piotr Sikora (PiotrSikora) | |
| 2020 Q3 | Yuchen Dai (lambdai) | |
| 2020 Q4 | Christoph Pakulski (cpakulski) | |
| 2021 Q1 | Rei Shimizu (Shikugawa) | |
| 2021 Q2 | Dmitri Dolguikh (dmitri-d) | |
| 2021 Q3 | Takeshi Yoneda (mathetake) | |
| 2021 Q4 | Otto van der Schaaf (oschaaf) | |
| 2022 Q1 | Otto van der Schaaf (oschaaf) | Ryan Hamilton (RyanTheOptimist) |
| 2022 Q2 | Pradeep Rao (pradeepcrao) | TBD |
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 deadline of 3 weeks.
| Version | Expected | Actual | Difference | End of Life |
|---|---|---|---|---|
| 1.12.0 | 2019/09/30 | 2019/10/31 | +31 days | 2020/10/31 |
| 1.13.0 | 2019/12/31 | 2020/01/20 | +20 days | 2021/01/20 |
| 1.14.0 | 2020/03/31 | 2020/04/08 | +8 days | 2021/04/08 |
| 1.15.0 | 2020/06/30 | 2020/07/07 | +7 days | 2021/07/07 |
| 1.16.0 | 2020/09/30 | 2020/10/08 | +8 days | 2021/10/08 |
| 1.17.0 | 2020/12/31 | 2021/01/11 | +11 days | 2022/01/11 |
| 1.18.0 | 2021/03/31 | 2021/04/15 | +15 days | 2022/04/15 |
| 1.19.0 | 2021/06/30 | 2021/07/13 | +13 days | 2022/07/13 |
| 1.20.0 | 2021/09/30 | 2021/10/05 | +5 days | 2022/10/05 |
| 1.21.0 | 2022/01/15 | 2022/01/12 | -3 days | 2023/01/12 |
| 1.22.0 | 2022/04/15 | 2022/04/15 | 0 days | 2023/04/15 |
| 1.23.0 | 2022/07/15 |
- Take a look at open issues tagged with the current release, by searching 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:
- 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.
- Switch the VERSION.txt from a "dev" variant to a final variant. E.g., "1.6.0-dev" to "1.6.0".
- Update the RELEASES 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.
- Create a tagged release. The release should start with "v" and be followed by the version number. E.g., "v1.6.0". This must match the VERSION.
- From the envoy landing page 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.
- Tagging will kick off another run of AZP postsubmit. 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.
- Update the website (example PR) 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 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 thetoctreein 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 anyref:links to point at the version - eg:ref:`Some link text <actual link>`->:ref:`Some link text <v1.16:actual link>` - Create a new "current" version history file at the release notes 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.
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.