Add documentation for Wasmtime's LTS releases (#10481)

alexcrichton · web-flow · commit 2de55ccf74a2 · 2025-03-31T18:49:16.000Z
* Add documentation for Wasmtime's LTS releases With Wasmtime's [LTS releases](bytecodealliance/rfcs#42) this commit documents the various process changes and updates to our release process. Additionally some improvements are made to the release documentation with respect to showing current versions. * Refactor some backport criteria docs * Review comments
diff --git a/README.md b/README.md
@@ -40,6 +40,10 @@ Windows or otherwise interested users can download installers and
 binaries directly from the [GitHub
 Releases](https://github.com/bytecodealliance/wasmtime/releases) page.
 
+Documentation on Wasmtime's currently supported versions can be found [in the
+online book
+documentation](https://docs.wasmtime.dev/stability-release.html#current-versions).
+
 ## Example
 
 If you've got the [Rust compiler
diff --git a/crates/wasmtime/README.md b/crates/wasmtime/README.md
@@ -115,5 +115,8 @@ Wasmtime can do for you or help answer your questions about Wasmtime. If you're
 curious in contributing to Wasmtime, [it can also help you do
 that][contributing]!
 
+For information on supported versions of Wasmtime see [the corresponding online book
+documentation](https://docs.wasmtime.dev/stability-release.html#current-versions).
+
 [contributing]: https://bytecodealliance.github.io/wasmtime/contributing.html
 [guide]: https://bytecodealliance.github.io/wasmtime
diff --git a/docs/book.toml b/docs/book.toml
@@ -5,4 +5,7 @@ src = "."
 title = "Wasmtime"
 
 [output.html]
+additional-js = ["js/moment.min.2.30.1.js", "js/mermaid.min.11.6.0.js", "js/index.js"]
 cname = "docs.wasmtime.dev"
+git-repository-url = "https://github.com/bytecodealliance/wasmtime"
+edit-url-template = "https://github.com/bytecodealliance/wasmtime/edit/main/docs/{path}"
diff --git a/docs/contributing-release-process.md b/docs/contributing-release-process.md
@@ -73,6 +73,18 @@ carry on its way.
 
 ## Releasing a patch version
 
+Wasmtime does not currently have a cadence for patch version nor a strict set
+of criteria. It's done on an as-needed basis. Two requirements, however are:
+
+* All changes must land on `main` first (if applicable) and then get backported
+  to an older branch. Release branches should already exist from the above
+  major release steps.
+
+* When a patch release is made it must be applied to [all supported
+  versions](./stability-release.md#current-versions) that need the patch.
+  Wasmtime will not release a patch release until all versions have been
+  equally patched to ensure that releases remain consistent.
+
 Making a patch release is somewhat more manual than a major version, but like
 before there's automation to help guide the process as well and take care of
 more mundane bits.
@@ -82,9 +94,6 @@ Like above human interaction is indicated with **bold** text in these steps.
 
 1. **Necessary changes are backported to the `release-2.0.0` branch from
    `main`**
-   * All changes must land on `main` first (if applicable) and then get
-     backported to an older branch. Release branches should already exist from
-     the above major release steps.
    * CI may not have been run in some time for release branches so it may be
      necessary to backport CI fixes and updates from `main` as well.
    * When merging backports maintainers need to double-check that the
@@ -132,3 +141,15 @@ the repository. Management of this file looks like:
 This means that `RELEASES.md` only has release notes for the release branch that
 it is on. Historical release notes can be found through links at the bottom to
 previous copies of `RELEASES.md`
+
+## Keeping Old release branch CI up-to-date
+
+Over time CI configuration goes out of date and may need to be updated. The
+Wasmtime repository has a cron job via GitHub Actions to run release CI on all
+supported release branches on a weekly basis to try to weed out these problems.
+If a release branch CI fails it'll open an issue and maintainers should resolve
+it expediently.
+
+Where possible old release branch CI should not update software to fix CI. Try
+to pin to older versions if something wasn't pinned already for example.
+Sometimes though updates are inevitable and may be required.
diff --git a/docs/js/index.js b/docs/js/index.js
@@ -0,0 +1,104 @@
+const WASMTIME_20 = moment.utc('2024-04-20');
+const DATE_FORMAT = 'MMMM D YYYY';
+
+function releaseDate(version) {
+  return WASMTIME_20.clone().add(version - 20, 'months');
+}
+
+function eolDate(version) {
+  const release = releaseDate(version);
+  if (version % 12 == 0)
+    return release.add(2, 'year');
+  return release.add(2, 'months');
+}
+
+function addReleases(table) {
+  const today = moment.utc();
+  const monthsSince20 = Math.floor(today.diff(WASMTIME_20, 'months'));
+  const currentRelease = 20 + monthsSince20;
+
+  // Add in some relevant releases, such as the current one, one future one, and
+  // two past ones.
+  let channels = [];
+  channels.push(currentRelease + 1);
+  channels.push(currentRelease);
+  channels.push(currentRelease - 1);
+  channels.push(currentRelease - 2);
+
+  // Add in historical LTS channels. Start with the current release and go
+  // backwards looking for two LTS channels.
+  let lts = 0;
+  let cur = currentRelease;
+  for (let cur = currentRelease; cur > 20 && lts < 2; cur--) {
+    if (cur % 12 == 0) {
+      channels.push(cur);
+      lts += 1;
+    }
+  }
+
+  // Add in a future LTS channel starting with the release after the current
+  // one.
+  for (let cur = currentRelease + 1; ; cur++) {
+    if (cur % 12 == 0) {
+      channels.push(cur);
+      break;
+    }
+  }
+
+  // Deduplicate and sort everything.
+  channels = [...new Set(channels)];
+  channels.sort();
+
+let mermaid = `
+gantt
+    tickInterval 12month
+    title Release Schedule
+    dateFormat  YYYY-MM
+`;
+
+  for (let channel of channels) {
+    const row = document.createElement('tr');
+    const date = releaseDate(channel);
+    const eol = eolDate(channel);
+
+    if (date <= today && today <= eol)
+      row.style.fontWeight = 'bold';
+
+    const version = document.createElement('td');
+    version.innerText = channel + '.0.0';
+    row.appendChild(version);
+
+    const lts = document.createElement('td');
+    if (channel % 12 == 0)
+      lts.innerText = '✅';
+    row.appendChild(lts);
+
+    const branch = document.createElement('td');
+    branch.innerText = date.clone().add(-15, 'days').format(DATE_FORMAT);
+    row.appendChild(branch);
+
+    const release = document.createElement('td');
+    release.innerText = date.format(DATE_FORMAT);
+    row.appendChild(release);
+
+    const eolRow = document.createElement('td');
+    eolRow.innerText = eol.format(DATE_FORMAT);
+    row.appendChild(eolRow);
+
+    dur = eol.diff(date, 'days')
+    mermaid += `    ${channel}.0.0    :a1, ${date.format('YYYY-MM-DD')}, ${dur}d\n`;
+
+    table.appendChild(row);
+  }
+
+  const gantt = document.createElement('pre');
+  gantt.classList.add('mermaid');
+  gantt.innerHTML = mermaid;
+  document.querySelector('#version-table').appendChild(gantt);
+}
+
+const table = document.querySelector('#version-table table tbody');
+if (table) {
+  addReleases(table);
+  mermaid.initialize({ theme: 'dark' });
+}
diff --git a/docs/js/mermaid.min.11.6.0.js b/docs/js/mermaid.min.11.6.0.js
diff --git a/docs/js/moment.min.2.30.1.js b/docs/js/moment.min.2.30.1.js
diff --git a/docs/security-vulnerability-runbook.md b/docs/security-vulnerability-runbook.md
@@ -37,8 +37,9 @@ is created these steps are followed:
    developed and the vulnerability is better understood at this point the
    description of the advisory should be fully filled out and be made ready to
    go to the public. This is also when the incident manager should determine the
-   number of versions of Wasmtime to patch. The latest two versions are
-   required, and older versions are optional.
+   number of versions of Wasmtime to patch. All [supported releases
+   documented](./stability-release.md) must be patched, but the incident manager
+   may also elect to patch more releases if desired.
 
 5. **Request a CVE**. Use the Big Green Button on the advisory to request a CVE
    number from GitHub staff.
diff --git a/docs/security-what-is-considered-a-security-vulnerability.md b/docs/security-what-is-considered-a-security-vulnerability.md
@@ -73,3 +73,6 @@ Note that we still want to fix every bug mentioned above even if it is not a
 security vulnerability! We appreciate when issues are filed for
 non-vulnerability bugs, particularly when they come with test cases and steps to
 reproduce!
+
+Backports for non-security related fixes is [documented
+here](./contributing-release-process.html#releasing-a-patch-version).
diff --git a/docs/stability-release.md b/docs/stability-release.md
@@ -1,18 +1,51 @@
 # Release Process
 
-Wasmtime's release process was [originally designed in an RFC][rfc4] and this
-page is intended to serve as documentation for the current process as-is today.
+Wasmtime's release process was [originally designed in an RFC][rfc4] and later
+amended with [an LTS process][rfc-lts] and this page is intended to serve as
+documentation for the current process as-is today.
+
 The high-level summary of Wasmtime's release process is:
 
-* A new major version of Wasmtime will be made available once a month.
-* Security bugs and correctness fixes will be backported to the latest two
-  releases of Wasmtime and issued as patch releases.
+* A new major version of Wasmtime will be made available on the 20th of each
+  month.
+* Each release that is a multiple of 12 is considered an LTS release and is
+  supported for 24 months. Other releases are supported for 2 months.
+* Security bugs are guaranteed to be backported to all supported releases.
+* Bug fixes are backported on a volunteer basis.
+
+[rfc-lts]: https://github.com/bytecodealliance/rfcs/pull/42
+
+## Current Versions
+
+<div id='version-table'>
+
+This is a table of supported, recent, and some upcoming releases of Wasmtime
+along with the dates around their release process. Rows in **bold** are
+actively supported at this time.
+
+| Version    | LTS | Branch Date | Release Date | EOL Date |
+|------------|-----|-------------|--------------|----------|
+
+<noscript>
+JavaScript is disabled so the table above is empty.
+</noscript>
+
+In more visual form this is a gantt chart of the current release trains:
+
+<noscript>
+JavaScript is disabled there is no gantt chart to show.
+</noscript>
+
+</div>
+
+
+## New Versions
 
 Once a month Wasmtime will issue a new major version. This will be issued with a
-semver-major version update, such as 4.0.0 to 5.0.0. The precise schedule of
-Wasmtime's release is currently an automated PR is sent to bump the version on
-the 5th of every month and a release is made when the PR is merged. The PR
-typically gets merged within a few days.
+semver-major version update, such as 4.0.0 to 5.0.0. Releases are created from
+main with a new `release-X.0.0` git branch on the 5th of every month. The
+release itself then happens on the 20th of the month, or shortly after if that
+happens to fall on a weekend.
 
 Each major release of Wasmtime reserves the right to break both behavior and API
 backwards-compatibility. This is not expected to happen frequently, however, and
@@ -28,18 +61,75 @@ any breaking change will follow these criteria:
   feedback about embeddings. Release notes will clearly indicate if any major
   breaking changes through accepted RFCs are included in a release.
 
+All releases will have an accompanying `RELEASES.md` on the release branch
+documenting major and minor changes made during development. Note that each
+branch only contains the release notes for that branch, but links are provided
+for older release notes.
+
+For maintainers, performing a release is [documented
+here](./contributing-release-process.md#releasing-a-major-version).
+
+## Version Support
+
+Wasmtime major version releases are of one of two categories:
+
+* LTS release - this happens every 12 releases of Wasmtime and the version
+  number is always divisible by 12. LTS releases are supported for 24 months.
+  For example Wasmtime 24.0.0 is supported for 2 years.
+
+* Normal release - this is every release other than an LTS release. Normal
+  releases are supported for 2 months. For example Wasmtime 31.0.0 is supported
+  for 2 months.
+
+At any one time Wasmtime has two supported LTS releases and up to two supported
+normal releases. Once a version of Wasmtime is release the project strives to
+maintain binary/version compatibility with dependencies and such throughout the
+lifetime of the release. For example the minimum supported version of Rust
+required to compile a version of Wasmtime will not increase. Exceptions may be
+made to LTS branches though if the versions of tooling to produce the LTS itself
+have fallen out-of-date. For example if an LTS was originally produced with a
+GitHub Actions runner that is no longer available then the oldest supported
+image will be used instead.
+
+## Patch Versions
+
 Patch releases of Wasmtime will only be issued for security and critical
-correctness issues for on-by-default behavior in the previous releases. If
-Wasmtime is currently at version 5.0.0 then 5.0.1 and 4.0.1 will be issued as
-patch releases if a bug is found. Patch releases are guaranteed to maintain API
-and behavior backwards-compatibility and are intended to be trivial for users to
-upgrade to.
+correctness issues for on-by-default behavior in supported releases. For example
+if the current version is 39.0.0 then a security issue would issue a new release
+for:
+
+* 39.0.x - the current release
+* 38.0.x - the last release
+* 36.0.x - the current LTS release
+* 24.0.x - the last LTS release
+
+Patch releases are guaranteed to maintain API and behavior
+backwards-compatibility and are intended to be trivial for users to upgrade to.
+
+The Wasmtime project guarantees backports and patch releases will be made for
+any discovered security issue. Other bug fixes are done on a best-effort basis
+in accordance with volunteers able to do the backports (see below). The Wasmtime
+project does not support backporting new features to older releases, even if a
+volunteer performs a backport for the project.
 
 Patch releases for Cranelift will be made for any miscompilations found by
 Cranelift, even those that Wasmtime itself may not exercise. Due to the current
 release process a patch release for Cranelift will issue a patch release for
 Wasmtime as well.
 
+Patch releases do not have a set cadence and are done on an as-needed basis. For
+maintainers, performing a patch release is [documented
+here](./contributing-release-process.md#releasing-a-patch-version).
+
+## Security Fixes
+
+Security fixes will be issued as patch releases of Wasmtime. They follow the
+same process as normal backports except that they're coordinated in private
+prior to patch release day.
+
+For maintainers, performing a security release is [documented
+here](./security-vulnerability-runbook.md).
+
 ## What's released?
 
 At this time the release process of Wasmtime encompasses:
