-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
RELEASES: add formal release policy for runc #4557
base: main
Are you sure you want to change the base?
Changes from all commits
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 |
---|---|---|
@@ -0,0 +1,110 @@ | ||
## Release Cadence and Support Policy ## | ||
|
||
This document describes the release cadence for runc as well as outlining the | ||
support policy for old release branches. Historically, despite runc being the | ||
most widely used Linux container runtime, our release schedule has been very | ||
ad-hoc and has resulted in very long periods of time between minor releases, | ||
causing issues for downstreams that wanted particular features. | ||
|
||
### Semantic Versioning ### | ||
|
||
runc uses [Semantic Versioning][semver] for releases. However, our | ||
compatibility policy only applies to the runc binary. We will make a | ||
best-effort attempt to reduce the impact to users that make direct use of the | ||
Go packages prefixed with `github.com/opencontainers/runc`, but we do not | ||
formally guarantee that API compatibility will be preserved. | ||
Comment on lines
+14
to
+15
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. Would it make sense to mention that we will try (best effort) include potentially breaking changes in the Go API as part of the release notes and users should familiarise themselves with the changes in the release notes before updating? We could also call out (but maybe we do somewhere) that (due to SemVer compatibility of the binary), updates of the runc binary may not require updating of runc library (go module) (this is mostly me having bad memories of containerd originally coupling those versions, resulting in go module updates for no practical reason). FWIW, I stumbled on this project, some time ago that may help checking for changes in the Go API (it may be limited, but could help as a tool in our tool belt) https://github.com/joelanford/go-apidiff |
||
|
||
[semver]: https://semver.org/spec/v2.0.0.html | ||
|
||
### Release Cadence ### | ||
|
||
> **NOTE**: At time of writing, this proposal is still a draft as we have not | ||
> yet done several releases using this cadence. If you have feedback on this | ||
> proposal (such as how well this proposal addresses your needs as a downstream | ||
> packager of runc), please feel free to [open an issue][new-issue] so we can | ||
> discuss it further. However, the current plan is for this proposal to be | ||
> followed for the `1.3.0` and `1.4.0` releases in 2025. | ||
|
||
[new-issue]: https://github.com/opencontainers/runc/issues/new/choose | ||
|
||
runc follows a 6-month minor version release schedule, with the aim of releases | ||
cyphar marked this conversation as resolved.
Show resolved
Hide resolved
|
||
happening at the end of April and October each year. | ||
|
||
The first release candidate will be created 2 months before the planned release | ||
date (i.e. the end of February and August, respectively), at which point the | ||
release branch will be created and will enter a feature freeze. No new features | ||
will be merged into the release branch, and large features being developed | ||
immediately before the feature freeze may have their merge delayed so as to not | ||
be included in the next release. Most releases will have two or three release | ||
candidates, but this may change depending on the circumstances of the release | ||
at the time. | ||
|
||
If a last-minute critical issue is discovered, the release may be delayed. | ||
However, the following release will still go according to schedule (except in | ||
the exceptionally unlikely scenario where the delay is 4-6 months long, in | ||
which case the next release is moved forward to when the subsequent release | ||
would have been). | ||
|
||
Here is a hypothetical release timeline to see how this works in practice: | ||
|
||
| Date | Release | Notes | | ||
| ---------- | ------------ | ----- | | ||
| 200X-02-28 | `1.3.0-rc.1` | `release-1.3` branch created, feature freeze. | | ||
cyphar marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 200X-03-12 | `1.3.0-rc.2` | | | ||
| 200X-03-25 | `1.3.0-rc.3` | | | ||
| 200X-04-30 | `1.3.0` | `1.3` release published. | | ||
| 200X-05-10 | `1.3.1` | | | ||
| 200X-06-21 | `1.3.2` | | | ||
| 200X-06-25 | `1.3.3` | | | ||
| 200X-07-02 | `1.3.4` | | | ||
| 200X-08-28 | `1.4.0-rc.1` | `release-1.4` branch created, feature freeze. | | ||
Comment on lines
+53
to
+60
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. So the only thing I'm wondering here with the example is that SemVer determines if a release will be major, minor, or patch; there may be roadmap items, but it's not a given that new features are to be added in any timeframe; i.e., with some parts of the container ecosystem stabilising, it's possible that we go 6 months without new features added. That means we can decide on a "check in" schedule to see;
With the above taken into account, I would consider
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 would personally prefer that we end up with a minor release without any new features rather than a delayed minor release because we didn't have a strict enough deadline. IMHO even if a minor release doesn't have many (or any) new features that's fine. SemVer says that minor bumps MUST be done for features, but it doesn't say they MUST NOT be done in absence of features (the wording of s6 sounds like it strongly disagrees with this point but s7 says that we can do minor releases in case of "It MAY be incremented if substantial new functionality or improvements are introduced within the private code" which is fairly carte blanche). And while it is a minor thing, doing minor releases means that we shorten the lifespan of release branches, which makes backports less painful. IMHO we've already tried to do the "we'll release once we have a new feature that deserves a release" approach and that doesn't seem to work for us (to be fair, we weren't strict enough about deadlines but I think a deadline decided that way is going to end up being somewhat loose). Having an automated deadline decided long in advance without needing to think about IMHO would make it easier for us and our users to plan around (not to mention it will make revert decisions much easier). It also means we only need to agree on this timeline once for the life of the project, rather than getting agreement for each minor release. |
||
| 200X-09-15 | `1.3.5` | Patch releases in other release branches have no impact on the new release branch. | | ||
| 200X-09-21 | `1.4.0-rc.2` | | | ||
| 200X-10-31 | `1.4.0` | `1.4` release published. | | ||
| 200X-11-10 | `1.4.1` | | | ||
| 200X-12-25 | `1.4.2` | | | ||
|
||
(And so on for the next year.) | ||
|
||
### Support Policy ### | ||
|
||
> **NOTE**: The following policy provides much longer support guarantees than | ||
> we have historically provided for older runc releases. In order to avoid | ||
> adding new support guarantees for old runc versions we have long-since | ||
> stopped supporting, the following support policy only applies for runc | ||
> releases from `1.2.0` onwards. In other words, runc `1.1.0` and `1.0.0` are | ||
> not guaranteed support by this policy. | ||
|
||
In order to ease the transition between minor runc releases, previous minor | ||
release branches of runc will be maintained for some time after the newest | ||
minor release is published. In the following text, `latest` refers to the | ||
latest minor (non-release-candidate) runc release published; `latest-1` is the | ||
previous minor release branch; and `latest-2` is the minor release branch | ||
before `latest-1`. For example, if `latest` is `1.4.0` then `latest-1` is | ||
`1.3.z` and `latest-2` is `1.2.z`. | ||
|
||
* Once `latest` is released, new features will no longer be merged into | ||
`latest` and only bug and security fixes will be backported, though we will | ||
be fairly liberal with what kinds of bugs will considered candidates for | ||
backporting. | ||
Comment on lines
+86
to
+89
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 guess this is already covered by describing that we follow SemVer for releases; Once a minor (i.e. "feature" release) is done, its set of features is frozen; any new feature requires updating the minor version. 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. It is, but given that we haven't always followed this in the past, it might be nice to make this explicit. |
||
|
||
* `latest-1` will only receive security fixes and significant bug fixes (what | ||
bug fixes are "significant" are down to the maintainer's judgement, but | ||
maintainers should err on the side of reducing the number of backports at | ||
this stage). At this stage, users of `latest-1` are encouraged to start | ||
planning the migration to the `latest` release of runc (as well as reporting | ||
any issues they may find). | ||
|
||
* `latest-2` will only receive high severity security fixes (i.e. CVEs that | ||
have been assessed as having a CVSS score of 7.0 or higher). At this stage, | ||
users still using `latest-2` would be strongly encouraged to upgrade to | ||
either `latest` or `latest-1`. | ||
|
||
* Any older releases will no longer receive any updates, and users are | ||
encouraged to upgrade in the strongest possible terms, as they will not | ||
receive any security fixes regardless of severity or impact. | ||
|
||
This policy only applies to minor releases of runc with major version `1`. If | ||
there is a runc `2.0` release in the future, this document will be updated to | ||
reflect the necessary changes to the support policy for the `1.y` major release | ||
branch of runc. |
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.
My pet-peeve with go modules having unilaterally claimed ownership of GitHub tags, and now interpreting them as SemVer for the Go API (whereas the intent was for
binary
releases) 😞