Skip to content
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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

RELEASES: add formal release policy for runc #4557

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions RELEASES.md
View file
Open in desktop
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
Comment on lines +11 to +12
Copy link
Member

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) 😞

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
Copy link
Member

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The 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;

  • what changes were merged (fixes, features)
  • what changes have been accepted and are expected to land in the given timeframe
  • depending on the accepted features (i.e., a contributing party may have proposed a feature that's accepted, and the contributing party may have communicated a desired (and realistic) timeframe, such a feature could be marked a "blocker" for the release

With the above taken into account, I would consider

  • feature releases having to be planned (proposed feature is accepted -> progress is checked -> preliminary date is set for the feature release)
  • non-feature releases (patch releases) could have a (say) monthly cadence if any fixes were merged
  • security / critical fixes to be an exception (to be announced ahead of time unless zero-day)

Copy link
Member Author

@cyphar cyphar Dec 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Member Author

Choose a reason for hiding this comment

The 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.
Loading