Rust fixes

docs/conf.py

@@ -280,7 +280,7 @@
 ]
 
 # Excludes files or directories from processing
-exclude_patterns = ["maintainers/NPM/common"]
+exclude_patterns = ["maintainers/niche-package-maintenance/rustc/common"]
 
 
 # Adds custom CSS files, located under 'html_static_path'

docs/contributors/bug-fix/propose-changes.rst

@@ -229,6 +229,8 @@ You can also use PPA-based method whenever possible. It produces results closest
 To learn how to set up and run these test methods, see `Running package tests <https://github.com/canonical/ubuntu-maintainers-handbook/blob/main/PackageTests.md>`_.
 
 
+.. _submitting-the-fix:
+
 Submitting the fix
 ------------------
 

docs/maintainers/index.md

@@ -42,10 +42,10 @@ SRU/index
 AA/index
 ```
 
-### Niche Package Maintenance
+### Niche package maintenance
 
 ```{toctree}
 :maxdepth: 1
 
-index-NPM
+niche-package-maintenance/index
 ```

docs/maintainers/niche-package-maintenance/index.md

@@ -0,0 +1,12 @@
+(niche-package-maintenance)=
+# Niche package maintenance
+
+Certain packages in the Archive are unique, and their maintenance procedures diverge somewhat from more conventional packages.
+
+Details on maintaining some of these packages are given here.
+
+```{toctree}
+:titlesonly:
+
+rustc/index
+```

docs/maintainers/niche-package-maintenance/rustc/index.md

@@ -0,0 +1,13 @@
+(rustc-packaging)=
+# `rustc` packaging
+
+How to update, package, and maintain versions of {pkg}`rustc` in Ubuntu.
+
+```{toctree}
+:maxdepth: 1
+
+Update Rust <update-rust>
+Patch Rust <patch-rust>
+Backport Rust <backport-rust>
+rust-version-strings
+```

docs/maintainers/NPM/npm-patching-rust.md → docs/maintainers/niche-package-maintenance/rustc/patch-rust.md

@@ -1,22 +1,19 @@
-(npm-patching-rust)=
-
-# rustc: Patching Rust
+(how-to-patch-rust)=
+# How to patch Rust
 
 This guide details the process of fixing an existing versioned `rustc` Ubuntu package.
 
-- To see the process of creating a _new_ versioned `rustc` package, consult the [Updating Rust](npm-updating-rust.md) guide instead.
-- To see the process of {term}`backporting <backport>` Rust, consult the [Backporting Rust](npm-backporting-rust.md) guide instead.
+- To see the process of creating a _new_ versioned `rustc` package, consult the {ref}`how-to-update-rust` guide instead.
+- To see the process of {term}`backporting <backport>` Rust, consult the {ref}`how-to-backport-rust` guide instead.
 
 ## Background
 
 Unfortunately, since `rustc` is a versioned {term}`source package`, we are unable to use the more modern {term}`git-ubuntu` ({manpage}`git-ubuntu(1)`) workflow. Whenever you must fix a bug in an already-released Rust source package, you must follow the legacy {manpage}`debdiff(1)` workflow instead.
 
 :::{attention}
-This guide assumes that you already have a basic understanding of maintaining Ubuntu packages in general. It _only_ covers the things which make Rust package patching unique.
+This guide assumes that you already have a basic understanding of maintaining Ubuntu packages in general. It _only_ covers the things that make Rust package patching unique.
 :::
 
----
-
 ```{include} common/substitution-terms.md
 
 ```
@@ -54,7 +51,7 @@ You must also verify that none of your changes have interfered with {term}`autop
 Once you've verified that your updated package builds properly in a PPA, passes all autopkgtests, and meets Lintian standards, then you're ready to create a reviewable diff using {manpage}`debdiff(1)`.
 
 :::{seealso}
-To get more info on the legacy `debdiff` process in general, consult the "Submitting the Fix" section of [this page](../../contributors/bug-fix/propose-changes.rst).
+To get more info on the legacy `debdiff` process in general, consult the {ref}`submitting-the-fix` section.
 :::
 
 Essentially, since the Git history of `rustc-<X.Y>` was wiped when it was uploaded as a new package, we need to manually generate a diff between the uploaded version of `rustc-<X.Y>` and your updated version of `rustc` that doesn't rely on Git. To do this, we'll need `.dsc`s for both package versions.
@@ -74,7 +71,7 @@ $ debdiff <old_dsc> <new_dsc> > 1-<new_full_version_number>.debdiff
 ### debdiff patch naming convention
 
 :::{important}
-An understanding of Rust-specific version string conventions is necessary for this portion. Read the ["Rust Version Strings"](npm-rust-version-strings.md) article before continuing.
+An understanding of Rust-specific version string conventions is necessary for this portion. Read the {ref}`rust-version-strings` article before continuing.
 :::
 
 Let's break down an example debdiff patch name: `1-1.86.0+dfsg0ubuntu2-0ubuntu1.debdiff`

docs/maintainers/NPM/npm-rust-version-strings.md → docs/maintainers/niche-package-maintenance/rustc/rust-version-strings.md

@@ -1,6 +1,5 @@
-(npm-rust-version-strings)=
-
-# rustc: Rust Version Strings
+(rust-version-strings)=
+# Rust version strings
 
 The Rust version string format used in the {term}`Ubuntu archive` is complicated and contains certain unique features.
 It's a combination of {term}`Debian` policy, Ubuntu conventions, and legacy code.
@@ -10,143 +9,137 @@ Although you will usually change only a few parts of the version string, it's a
 An understanding of how [Ubuntu version strings normally work](version-strings) is mandatory before this article can be read.
 :::
 
-## The Full Breakdown
 
-Here, `{curly_braces}` indicate placeholders to be edited, while `[square_brackets]` indicate optional parts.
+## Full breakdown
+
+Here, `<angle_brackets>` indicate placeholders to be edited, while `[square_brackets]` indicate optional parts.
 
 ```none
-{rust_version}+dfsg0ubuntu{repack}[~bpo{vendored_dependencies}]-0ubuntu{revision}.[{ubuntu_release}][~ppa{PPA}]
+<rust_version>+dfsg0ubuntu<repack>[~bpo<vendored_dependencies>]-0ubuntu<revision>.[<ubuntu_release>][~ppa<PPA>]
 ```
 
----
 
-## {rust_version}
+## `<rust_version>`
 
 > _The upstream Rust toolchain version._
 
-This is simple; it's just the {term}`upstream` version of the given Rust toolchain. It's only updated when [adding a new Rust version to the archive](npm-updating-rust.md).
+This is simple; it's just the {term}`upstream` version of the given Rust toolchain. It's only updated when {ref}`adding a new Rust version to the archive <how-to-update-rust>`.
 
-### {rust_version} Examples
+**Examples:**
 
 - `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`: Rust 1.88.0
 - `1.87.0+dfsg0ubuntu1-0ubuntu1`: Rust 1.87.0
 - `1.85.1+dfsg0ubuntu2-0ubuntu2~ppa3`: Rust 1.85.1
 - `1.80.0+dfsg0ubuntu1~bpo2-0ubuntu0.24.09~ppa4`: Rust 1.80.0
 
----
-
-(rust-version-strings-repack)=
 
-## `+dfsg0ubuntu{repack}`
+(dfsg0ubuntu-repack)=
+## `+dfsg0ubuntu<repack>`
 
 > _The number of times you have edited Files-Excluded._
 
 `dfsg` is short for "Debian {term}`free software` guidelines."
-The presence of `+dfsg{whatever}` in any package indicates that the {term}`orig tarball` has been _repacked_ in some way.
+The presence of `+dfsg<whatever>` in any package indicates that the {term}`orig tarball` has been _repacked_ in some way.
 
 Usually, this is done for copyright reasons.
 However, in this case, we are doing it to make our tarballs smaller.
 Rust comes with a lot of functionality that we don't need, most notably Windows support.
 To save space, we use Debian's ability to _exclude_ all those unnecessary files from the tarball.
 That way, we aren't hauling around megabytes of code the compiler is going to ignore anyways.
 
-Returning to `+dfsg0ubuntu{repack}`, since we don't use Debian's upstream package, the number after `dfsg` shall always be `0`, because Debian won't have repacked the tarball.
-We (`ubuntu`) have repacked it `{repack}` times.
+Returning to `+dfsg0ubuntu<repack>`, since we don't use Debian's upstream package, the number after `dfsg` shall always be `0`, because Debian won't have repacked the tarball.
+We (`ubuntu`) have repacked it `<repack>` times.
 
-Since we always repack the tarball when [updating the Rust version](npm-updating-rust.md), a newly-released versioned Rust package will always use `+dfsg0ubuntu1`.
+Since we always repack the tarball when {ref}`updating the Rust version <how-to-update-rust>`, a newly-released versioned Rust package will always use `+dfsg0ubuntu1`.
 
-```{note}
-The ["Updating Rust"](npm-updating-rust.md) docs instruct you to start with `+dfsg0ubuntu0` in the version number.
+:::{note}
+The {ref}`how-to-update-rust` docs instruct you to start with `+dfsg0ubuntu0` in the version number.
 This is because it's simply an interim number that will be replaced with `+dfsg0ubuntu1` once the package is ready for upload.
-```
+:::
 
-### Examples
+**Examples:**
 
 - `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`: 1st repack
 - `1.87.0+dfsg0ubuntu1-0ubuntu1`: 1st repack
 - `1.85.1+dfsg0ubuntu2-0ubuntu2~ppa3`: 2nd repack
 - `1.80.0+dfsg0ubuntu1~bpo2-0ubuntu0.24.09~ppa4`: 1st repack
 
----
 
-## [~bpo{vendored_dependencies}]
+## `[~bpo<vendored_dependencies>]`
 
 > _Code number for what dependencies are {term}`vendored <vendored dependency>`._
 
 This portion of the version string is applicable to {term}`backports <backport>` _only_.
-More info on Rust backports can be found [here](npm-backporting-rust.md).
+More info on Rust backports can be found in {ref}`how-to-backport-rust`.
 
 If you have {term}`vendored <vendored dependency>` LLVM or `libgit2` for your backport, then you must include this part.
 Otherwise, then this portion must be omitted entirely.
 
-`{vendored_dependencies}` is a code number:
+`<vendored_dependencies>` is a code number:
 
 - `0` when `libgit2` _and_ LLVM are vendored
 - `2` when _only_ LLVM is vendored, and the system `libgit2` is used
 - `10` when _only_ `libgit2` is vendored, and the system `LLVM` is used
 
-### Examples
+**Examples:**
 
 - `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`: No vendored dependencies
 - `1.87.0+dfsg0ubuntu1-0ubuntu1`: No vendored dependencies
 - `1.85.1+dfsg0ubuntu2-0ubuntu2~ppa3`: No vendored dependencies
 - `1.80.0+dfsg0ubuntu1~bpo2-0ubuntu0.24.09~ppa4`: Only LLVM is vendored
 - `1.83.0+dfsg0ubuntu1~bpo0-0ubuntu0.24.09~ppa1`: Both `libgit2` and LLVM are vendored
 
----
 
-## 0ubuntu{revision}
+## `0ubuntu<revision>`
 
 > _The "real" version._
 
 This is the component that actually indicates the number of times you have edited this particular package.
 Every time you need to edit a particular version of Rust on a particular version of Ubuntu, you increment this number.
 
-`{revision}` starts at 1.
-When [creating a new Rust release package for the archive](npm-updating-rust.md), this portion will always be `0ubuntu1` upon upload to the archive.
+`<revision>` starts at 1.
+When {ref}`creating a new Rust release package for the archive <how-to-update-rust>`, this portion will always be `0ubuntu1` upon upload to the archive.
 
-```{note}
-The ["Updating Rust"](npm-updating-rust.md) docs instruct you to start with `0ubuntu0` in the version number.
+:::{note}
+The {ref}`how-to-update-rust` docs instruct you to start with `0ubuntu0` in the version number.
 This is because it's simply an interim number that will be replaced with `0ubuntu1` once the package is ready for upload.
-```
+:::
 
-When [updating an existing Rust toolchain in the archive](npm-patching-rust.md), `{revision}` will be incremented.
+When {ref}`updating an existing Rust toolchain in the archive <how-to-patch-rust>`, `<revision>` will be incremented.
 
-This number gets reset back to 1 whenever [`{repack}`](rust-version-strings-repack) is incremented.
+This number gets reset back to 1 whenever {ref}`'repack' <dfsg0ubuntu-repack>` is incremented.
 For example, repacking `1.82.0+dfsg0ubuntu1-0ubuntu3` means the new version number would be `1.82.0+dfsg0ubuntu2-0ubuntu1`.
 
-### Examples
+**Examples:**
 
 - `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`: First Revision
 - `1.87.0+dfsg0ubuntu1-0ubuntu1`: First Revision
 - `1.85.1+dfsg0ubuntu2-0ubuntu2~ppa3`: Second Revision (#2)
 
----
 
-## [{ubuntu_release}]
+## `[<ubuntu_release>]`
 
 > _The Ubuntu release in case of backport, plus some hacks._
 
 This portion of the version string is applicable to {term}`backports <backport>` _only_.
-More info on Rust backports can be found [here](npm-backporting-rust.md).
+More info on Rust backports can be found in {ref}`how-to-backport-rust`.
 
 In theory, this part is simple: it's the number of the Ubuntu release this backport is for.
 In practice, however, there's a catch; while the backport is a work-in-progress, decrement the last number by 1.
 That way it always sorts before the finalized version.
 
 This portion is omitted entirely if this is not a backport.
 
-### Examples
+**Examples:**
 
 - `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`: Not a backport
 - `1.87.0+dfsg0ubuntu1-0ubuntu1`: Not a backport
 - `1.80.0+dfsg0ubuntu1~bpo2-0ubuntu0.24.09`: WIP, for Ubuntu 24.10 (that's Oracular Oriole)
 - `1.83.0+dfsg0ubuntu1-0ubuntu1.24.03~ppa3`: WIP, for Ubuntu 24.04 (that's Noble Numbat)
 - `1.83.0+dfsg0ubuntu1~bpo0-0ubuntu1.24.04`: Complete, for Ubuntu 24.04 (again, Noble Numbat)
 
----
 
-## [~ppa{PPA}]
+## `[~ppa<PPA>]`
 
 > _The number of times you have pushed it to your PPA for testing._
 
@@ -160,24 +153,23 @@ Every time you change the rest of the version string in some way, you can reset
 If this part is _not_ present, that means it's on the main archive, so it's a version that's actually out.
 
 :::{note}
-{term}`Changelog` (`debian/changelog`) entries with `~ppa{PPA}` should should never make itonto a {term}`version control system`; they are only for the benefit of the PPA itself.
+{term}`Changelog` (`debian/changelog`) entries with `~ppa<PPA>` should should never make itonto a {term}`version control system`; they are only for the benefit of the PPA itself.
 When working on a Rust toolchain locally, the PPA-specific changelog entry (and version string) should be removed after successful PPA upload.
 :::
 
-### Examples:
+**Examples:**
 
 - `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`: First push to your PPA
 - `1.87.0+dfsg0ubuntu1-0ubuntu1`: No PPA (i.e., real complete release)
 - `1.85.1+dfsg0ubuntu2-0ubuntu2~ppa3`: 3rd push to your PPA
 
----
 
-## Putting it All Together
+## Putting it all together
 
 To recap, let's do a complete breakdown of some example version strings:
 
-| String                                         | {rustc_version} | {repack} | ~bpo{vendored_dependencies} | {revision} | {ubuntu_release}                  | ~ppa{PPA} |
-| ---------------------------------------------- | --------------- | -------- | --------------------------- | ---------- | --------------------------------- | --------- |
-| `1.80.0+dfsg0ubuntu1~bpo2-0ubuntu0.24.09~ppa4` | 1.80.0          | 1        | 2, so only LLVM             | 0          | In-dev backport for 24.10 (OO)    | 4         |
-| `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1`            | 1.88.0          | 1        | System libgit2 and LLVM     | 1          | Omitted b/c this is a normal port | 1         |
-| `1.83.0+dfsg0ubuntu1~bpo0-0ubuntu1.24.03~ppa3` | 1.83.0          | 2        | 0, so both libgit2 and LLVM | 1          | In-dev backport for 24.03 (NN)    | 3         |
+| String | `<rustc_version>` | `<repack>` | `~bpo<vendored_dependencies>` | `<revision>` | `<ubuntu_release>`                 | `~ppa<PPA>` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `1.80.0+dfsg0ubuntu1~bpo2-0ubuntu0.24.09~ppa4` | 1.80.0 | 1 | 2, so only LLVM | 0 | In-dev backport for 24.10 (OO) | 4 |
+| `1.88.0+dfsg0ubuntu1-0ubuntu1~ppa1` | 1.88.0 | 1 | System libgit2 and LLVM | 1 | Omitted b/c this is a normal port | 1 |
+| `1.83.0+dfsg0ubuntu1~bpo0-0ubuntu1.24.03~ppa3` | 1.83.0 | 2 | 0, so both libgit2 and LLVM | 1 | In-dev backport for 24.03 (NN) | 3 |

docs/maintainers/NPM/npm-updating-rust.md → docs/maintainers/niche-package-maintenance/rustc/update-rust.md

@@ -1,14 +1,13 @@
-(npm-updating-rust)=
-
-# rustc: Updating Rust
+(how-to-update-rust)=
+# How to update Rust
 
 This guide details the process of creating a new versioned `rustc` Ubuntu package for a new upstream Rust release.
 
-- To see the process of {term}`backporting <backport>` Rust, consult the [Backporting Rust](npm-backporting-rust.md) guide instead.
-- To see the process of fixing an existing Rust package, consult the [Patching Rust](npm-patching-rust.md) guide instead.
+- To see the process of {term}`backporting <backport>` Rust, consult the {ref}`how-to-backport-rust` guide instead.
+- To see the process of fixing an existing Rust package, consult the {ref}`how-to-patch-rust` guide instead.
 
 :::{attention}
-This is _not_ a guide for updating your system's Rust toolchain. This guide is intended only for Ubuntu toolchain package maintainers seeking to add new Rust versions to the Ubuntu archive.
+This is _not_ a guide for updating your system's Rust toolchain. This guide is intended only for Ubuntu toolchain package maintainers seeking to add new Rust versions to the Ubuntu Archive.
 :::
 
 ## Background
@@ -110,7 +109,7 @@ $ dch -v <X.Y.Z>+dfsg0ubuntu0-0ubuntu0
 ```
 
 :::{important}
-The changelog version string is complicated. It's _strongly recommended_ to consult the ["Rust Version Strings"](npm-rust-version-strings.md) article before making this change to ensure you understand the version string.
+The changelog version string is complicated. It's _strongly recommended_ to consult the {ref}`rust-version-strings` article before making this change to ensure you understand the version string.
 
 Even though the `ubuntu` suffix in version strings starts at 1, the fact that both suffixes are `ubuntu0` here is not a typo. This version string will _not_ be added to the archive — it is simply an interim number to be used temporarily until we're finished repacking the tarball.
 :::