Merge branch 'main' into agent/add-html-parsing-guide

Author: Arsybai

runtime/fundamentals/stability_and_releases.md

@@ -1,5 +1,5 @@
 ---
-last_modified: 2026-07-06
+last_modified: 2026-07-16
 title: "Stability and releases"
 description: "Guide to Deno's stability guarantees and release process. Covering release channels, long-term support (LTS), unstable features, versioning policy, and how Deno maintains backward compatibility."
 oldUrl:
@@ -21,46 +21,87 @@ released.
 
 ### Release channels
 
-Deno offers 3 release channels
+Deno is distributed on four release channels. Each channel is an independent
+track with its own "latest" version and its own download location, so moving
+along one track never moves you along another:
 
-- `stable` - a semver minor/patch release, as described above. This is **the
-  default** distribution channel that is recommended for most users.
+- `stable` - semver minor/patch releases, as described above. This is **the
+  default** channel and is recommended for most users. Stable builds are
+  downloaded from [GitHub releases](https://github.com/denoland/deno/releases).
+- `lts` - long term support: a single stable minor line that receives only
+  backwards-compatible bug fixes, recommended for enterprise users who prefer
+  not to upgrade so often. See [Long Term Support](#long-term-support-(lts)).
 - `rc` - a release candidate for the upcoming semver minor release.
-- `canary` - an unstable release that changes multiple times per day, allows to
-  try out latest bug fixes and new features that might end up in the `stable`
-  channel.
-
-An `lts` (long term support) channel was previously offered, but it has been
-discontinued. See below for details.
-
-### Long Term Support (LTS) - discontinued
-
-:::warning
-
-LTS support was discontinued on April 30, 2026. There are no LTS releases or
-maintenance beyond that date. If you are still using an LTS release, upgrade to
-the latest `stable` release.
-
-:::
-
-From February 2025 to April 2026, Deno offered an LTS (long-term support)
-channel: a minor semver version maintained with only backwards-compatible bug
-fixes. The final LTS release was v2.5, which reached end of life on April 30,
-2026.
+- `canary` - an unstable build that changes multiple times per day, so you can
+  try the latest bug fixes and features before they reach `stable`.
+
+During a major-version prerelease cycle (such as 3.0), Deno also publishes
+`alpha` and `beta` channels. Every channel except `stable` is served from Deno's
+download server at `dl.deno.land`.
+
+### Choosing a channel
+
+Your installed Deno belongs to exactly one channel, and that channel is baked
+into the binary when it is built. `deno upgrade` reads your current binary's
+channel to decide what "latest" means, and the update notice you occasionally
+see is based on the same thing. An LTS binary, for example, prints
+`A new LTS release of Deno is available` and tells you to run
+`deno upgrade lts`.
+
+A version number does not, by itself, identify a channel. The same version can
+ship as two byte-different builds: `2.9.3`, for instance, exists both as a
+stable release and as an LTS release. They are built from the same source and
+carry the same version string, and differ only in an embedded channel marker and
+where they are downloaded from. There is no way to ask for "the LTS build of
+2.9.3" by version number, because the version string is identical for both. You
+select a build by channel, not by version, and a bare version number always
+resolves to the **stable** build.
+
+| Command                   | Resolves to                             | Resulting build |
+| ------------------------- | --------------------------------------- | --------------- |
+| `deno upgrade`            | latest **stable** release               | stable          |
+| `deno upgrade 2.9.3`      | version 2.9.3 on the **stable** channel | stable          |
+| `deno upgrade lts`        | latest **lts** release                  | lts             |
+| `deno upgrade rc`         | latest **rc** release                   | rc              |
+| `deno upgrade canary`     | latest canary build                     | canary          |
+| `deno upgrade <git-hash>` | that specific canary build              | canary          |
+
+To switch channels on purpose, pass the channel name, for example
+`deno upgrade lts` or `deno upgrade stable`. Because a plain version number
+always selects the stable build, a user on LTS who runs `deno upgrade 2.9.3`
+downloads the stable build and moves off the `lts` channel onto `stable`. To
+stay on LTS, upgrade with `deno upgrade lts`.
+
+A channel name always resolves to that channel's newest build, so
+`deno upgrade lts` installs the latest LTS release and there is no
+`deno upgrade` form that pins an older LTS patch version. A version number only
+ever selects a stable (or `rc`, `alpha`, `beta`) build, never an LTS one. See
+[`deno upgrade`](/runtime/reference/cli/upgrade/) for more.
+
+### Long Term Support (LTS)
+
+Deno offers an LTS (long-term support) channel: a single stable minor line that
+we maintain with only backwards-compatible bug fixes. It is aimed at enterprise
+users who prefer to stay on one release line without absorbing new features or
+breaking changes. Install or update it with `deno upgrade lts`.
+
+The LTS channel is active on the Deno 2.9 line, starting with **v2.9.3**, and is
+maintained until January 31st, 2027.
 
 | LTS release version | LTS maintenance start | LTS maintenance end |
 | ------------------- | --------------------- | ------------------- |
 | v2.1                | Feb 1st, 2025         | Apr 30th, 2025      |
 | v2.2                | May 1st, 2025         | Oct 31st, 2025      |
 | v2.5                | Nov 1st, 2025         | Apr 30th, 2026      |
+| v2.9                | Jul 1st, 2026         | Jan 31st, 2027      |
 
-LTS backports included:
+LTS backports include:
 
 - Security patches
 - Critical bug fixes (e.g., crashes, incorrect computations)
-- **Critical** performance improvements, backported based on severity
+- **Critical** performance improvements _may_ be backported based on severity.
 
-API changes and major new features were not backported.
+**API changes and major new features will not be backported.**
 
 ## Unstable APIs
 

runtime/reference/cli/upgrade.md

@@ -1,5 +1,5 @@
 ---
-last_modified: 2026-05-20
+last_modified: 2026-07-15
 title: "deno upgrade"
 oldUrl: /runtime/manual/tools/upgrade/
 command: upgrade
@@ -51,6 +51,44 @@ Version has been found
 Would upgrade to version 1.38.5
 ```
 
+## Channels
+
+`deno upgrade` works one channel at a time. With no argument it upgrades to the
+latest **stable** release. Pass a channel name to move to that channel's latest
+build instead:
+
+```sh
+# Latest stable release (the default)
+deno upgrade
+
+# Latest long term support (LTS) release
+deno upgrade lts
+
+# Latest release candidate
+deno upgrade rc
+
+# Latest canary build
+deno upgrade canary
+```
+
+A bare version number is always a **stable** coordinate. `deno upgrade 2.9.3`
+installs the stable build of 2.9.3, even when the same version number also ships
+on another channel:
+
+```sh
+deno upgrade 2.9.3
+```
+
+Because of this, if you are on the LTS channel and run `deno upgrade 2.9.3`, you
+download the stable build and move off LTS onto stable. To stay on LTS, upgrade
+with `deno upgrade lts`.
+
+Note that `deno upgrade lts` always installs the latest LTS release. There is no
+version-number form that selects a specific LTS build, since a version number
+always resolves to the stable channel. For the full mental model of channels and
+how the same version number can be two different builds, see
+[Stability and releases](/runtime/fundamentals/stability_and_releases/#choosing-a-channel).
+
 ## --quiet flag
 
 The `--quiet` flag suppresses diagnostic output during the upgrade process. When