From 30eefddc7e62e99af12762e107afaa4950af69a9 Mon Sep 17 00:00:00 2001 From: Max Gilmour Date: Thu, 20 Nov 2025 14:45:56 -0800 Subject: [PATCH] Update Rust version string documentation with new version string format The old version string docs have been retained just in case someone needs to work on a Rust toolchain with the old format. --- .../rustc/rust-version-strings.md | 181 +++++++++++++++++- .../rustc/update-rust.md | 1 + 2 files changed, 181 insertions(+), 1 deletion(-) diff --git a/docs/maintainers/niche-package-maintenance/rustc/rust-version-strings.md b/docs/maintainers/niche-package-maintenance/rustc/rust-version-strings.md index 0e3c17b0..399da838 100644 --- a/docs/maintainers/niche-package-maintenance/rustc/rust-version-strings.md +++ b/docs/maintainers/niche-package-maintenance/rustc/rust-version-strings.md @@ -10,7 +10,186 @@ An understanding of how [Ubuntu version strings normally work](version-strings) ::: -## Full breakdown +## A Typical Rust Version String + +Components in `[square brackets]` are placeholders to be filled in, while components in `` are optional. + +The version string format for a versioned `rustc-X.Y` {term}`source package` is as follows: + +```none +[upstream_version]+dfsg<[repack_number]>-0ubuntu[ubuntu_revision] +``` + +### `[upstream_version]` + +This component shows what upstream version of the Rust toolchain this package is. Since Ubuntu Rust toolchain packages are versioned, this number only changes if the upstream Rust Foundation releases a patch for the current release, e.g., `1.85.0` -> `1.85.1`. + +If the Rust Foundation releases a new patch release, then the rest of the version number gets reset back to `+dfsg-0ubuntu1`. + +> Example: `1.85.0+dfsg3-0ubuntu5` -> `1.85.1+dfsg-0ubuntu1` + +(rust-repack-number)= +### `+dfsg<[repack_number]>` + +This component signifies that the original upstream source has been modified from its original state, i.e., the {term}`orig tarball` has been repacked. + +The `+dfsg` component is _always_ there because during the `rustc` update process, several unneeded dependencies are [pruned from the upstream source](pruning-unwanted-dependencies). + +Normally, the `[repack_number]` can be elided entirely. However, if after the first release the {term}`orig tarball` must be repacked for whatever reason, a `[repack_number]` must be added afterwards, starting at `1`. + +If this number must be incremented, then the `[ubuntu_revision]` (described [below](rust-ubuntu-revision)) must be reset back to `1`. + +> Example: `1.85.1+dfsg-0ubuntu3` -> `1.85.1+dfsg1-0ubuntu1` + +Here are some examples of this component: + +| Component | Meaning | +|-----------|----------------------------------------------------------------------| +| `+dfsg` | This tarball has not been modified since the initial package upload. | +| `+dfsg1` | This tarball has been modified after the original package upload. | +| `+dfsg2` | This tarball has been modified twice. | + +(rust-ubuntu-revision)= +### `-0ubuntu[ubuntu_revision]` + +Finally, this component shows how many modifications the Ubuntu maintainers have made to this Rust toolchain. For the first upload, `[ubuntu_revision]` starts at `1`. + +The '`0`' in the `0ubuntu[ubuntu_revision]` component signifies that this package is separate from Debian and will _never_ be synced. + +If the `[]` described [above](rust-repack-number) is ever added or incremented, `[ubuntu_revision]` is reset back to `1`. + +Here are some examples of this component: + +| Component | Meaning | +|-------------|----------------------------------------------------------| +| `-0ubuntu1` | Initial upload for the given upstream source. | +| `-0ubuntu3` | The third Ubuntu revision for the given upstream source. | + +### Example: Uploading and Updating a New Rust Toolchain + +Let's say you're uploading Rust 1.95 as the new `rustc-1.95` package for the first time. On your initial upload, you'll make the version string the following: + +```none +1.95.0+dfsg-0ubuntu1 +``` + +Now, assume you need to fix a bug. You must then increment `[ubuntu_revision]`, making the version string for your next upload the following: + +```none +1.95.0+dfsg-0ubuntu2 +``` + +Next, imagine that you accidentally included an unwanted dependency in the orig tarball and you must prune it out. When you upload this fixed version, you add a `1` after `+dfsg`, resetting `[ubuntu_revision]` back to `1`: + +```none +1.95.0+dfsg1-0ubuntu1 +``` + +Next, imagine the upstream Rust Foundation creates a patch release for Rust 1.95. After you've synced the package with the new upstream source, you must update the `[upstream_version]`, resetting the rest of the version number: + +```none +1.95.1+dfsg-0ubuntu1 +``` + +Here's what that same version number would look like after uploading another Ubuntu-specific fix: + +```none +1.85.1+dfsg-0ubuntu2 +``` + + +## A Rust Backport Version String + +A {term}`backported ` Rust toolchain follows the same rules as a normal upload, with a few modifications: + +```none +[upstream_version]+dfsg<[repack_number]><~[repack_series]<.[backport_repack]>>-0ubuntu0.[series_number].[ubuntu_revision] +``` + +### `<~[repack_series]<.[backport_repack]>>` + +During backporting, there are certain cases in which the Rust toolchain's dependencies can't be met because the archive is too old. When this happens, the dependencies must be {term}`vendored `, i.e., included in the orig tarball. (This commonly happens with [LLVM](rust-vendoring-llvm) and [`libgit2`](rust-vendoring-libgit2).) + +If this is necessary, the existing `[repack_number]` is untouched. Instead, `~[repack_series]` is added, which shows that the tarball has been repacked for this specific {term}`Ubuntu series `. + +If, after the initial backport upload, the orig tarball must be modified _again_, `.[backport_repack]` is added and incremented as necessary. + +Here are some examples of this component: + +| Component | Meaning | +|-----------------|-------------------------------------------------------------------------------------------| +| `+dfsg` | The orig tarball is the same as the original upload. | +| `+dfsg~22.04` | The orig tarball was modified for a 22.04 backport. | +| `+dfsg1~24.04` | The orig tarball, revised in the original upload, was also modified for a 24.04 backport. | +| `+dfsg~25.10.1` | The orig tarball had to be modified for a 25.10 backport, then revised later. | + +### `-0ubuntu0.[series_number].[ubuntu_revision]` + +We don't want the backport version number to sort newer than any non-backported version in the archive. Therefore, the original Ubuntu revision is replaced by `0.[series_number].[ubuntu_revision]`. + +The `[series_number]` signifies the particular series this backport targets. + +The `[ubuntu_revision]` component acts just like the [standard `[ubuntu_revision]` component](rust-ubuntu-revision) — it starts at `1` and is incremented as necessary. + +Here are some examples of this component: + +| Component | Meaning | +|---------------------|---------------------------------------------------------------------| +| `-0ubuntu0.22.04.1` | This is the initial upload of the 22.04 backport. | +| `-0ubuntu0.20.10.2` | This 20.10 backport has been revised once after the initial upload. | + + +### Example: Backporting a Rust Toolchain + +Let's say you need to backport the following Rust toolchain to 24.04: + +```none +1.90.0+dfsg2-0ubuntu3 +``` + +Assume that you don't need to modify the orig tarball. Your backport's version string will look like this: + +```none +1.90.0+dfsg2-0ubuntu0.24.04.1 +``` + +Now, imagine you need to fix a bug and upload a new version of this backport: + +```none +1.90.0+dfsg2-0ubuntu0.24.04.2 +``` + +Next, imagine you need to backport this toolchain to 22.04. For _this_ backport, LLVM has to be vendored, meaning you needed to modify the orig tarball. The new version string is the following: + +```none +1.90.0+dfsg2~22.04-0ubuntu0.22.04.1 +``` + +Now, imagine you need to backport this toolchain to 20.04. Here, no further modifications to the orig tarball were necessary, so `[repack_series]` can remain the same, as we're still using the orig tarball from the 22.04 backport: + +```none +1.90.0+dfsg2~22.04-0ubuntu0.20.04.1 +``` + +Imagine one more backport to 18.04. In this case, `libgit2` _also_ had to be vendored, meaning that a new tarball had to be repacked for the 18.04 backport: + +```none +1.90.0+dfsg2~18.04-0ubuntu0.18.04.1 +``` + +Finally, imagine that there was an issue with the 18.04 repack, requiring another orig tarball to be uploaded: + +```none +1.90.0+dfsg2~18.04.1-0ubuntu0.18.04.1 +``` + +## Legacy Version String Format + +:::{important} +This format is _no longer used_! + +It's possible you may need to work with older versions of the Rust toolchain with potentially-confusing version strings. While these formats are no longer used, they should help one understand the version strings of these older toolchains. +::: Here, `` indicate placeholders to be edited, while `[square_brackets]` indicate optional parts. diff --git a/docs/maintainers/niche-package-maintenance/rustc/update-rust.md b/docs/maintainers/niche-package-maintenance/rustc/update-rust.md index 9cb3244b..f20974d6 100644 --- a/docs/maintainers/niche-package-maintenance/rustc/update-rust.md +++ b/docs/maintainers/niche-package-maintenance/rustc/update-rust.md @@ -224,6 +224,7 @@ Finally, `debian/patches/prune/d-0021-vendor-remove-windows-dependencies.patch` You will later have to manually update this patch, so you may simply refresh this patch after force-applying it, dropping all the missing vendored crates. +(pruning-unwanted-dependencies)= ### Pruning Unwanted Dependencies As mentioned above, we don't want to include unnecessary dependencies, especially Windows-related crates like `windows-sys`. This pruning ensures adherence to free software principles, reduces the attack surface of the binary packages, and reduces the binary package size on the end user's hard drive.