Refresh Rust versions
Move every resource to the latest stable Rust release and the latest edition, and every crate pin in templates/Cargo.toml to its latest stable version.
"This repository" in this skill means awesome-humans/rust. Run the skill in a checkout, where each path in it, such as opinions/ or templates/Cargo.toml, is relative to the repository's root.
Trigger
The .github/workflows/rust-release-watch.yml workflow checks the official stable channel manifest daily. When the stable release changes, it opens a trigger pull request labelled rust-release on the branch automation/rust-release-watch.
- The trigger pull request only updates the snapshot in
.github/state/rust-releases.json. - Run this skill on that branch to make the update, and merge both together.
- You can also run the skill by itself. The snapshot answers "Which stable release does this repository know about?" offline.
Orchestration
As AGENTS.md: Orchestration and model economy describes, delegate the web lookups to worker agents: the version checks in step 1, the crates.io lookups in step 4b, and the release-notes reading in step 5. Only the editor decides what changes, and edits opinions/ and templates/.
Steps
- Find the latest released versions.
- Rust:
pkg.rust.versionin channel-rust-stable.toml, and the release announcement on the Rust Blog. - The edition: the Edition Guide.
- Use stable releases only. A beta or nightly feature can appear in a "Coming next" note, never as the target.
- Rust:
- Compare with the current targets: the
targets:metadata inopinions/, the version pins intemplates/, and the rootrust-toolchain.tomlandCargo.toml. The template pins arechannelinrust-toolchain.toml, andeditionandrust-versionin eachCargo.toml.targets:names the minor release, such asrust-1.99, so a point release such as 1.99.1 changes no target.- If everything matches, the toolchain part has nothing to do. Say so, and still run step 4b, because crate pins drift on their own schedule.
- Report "up to date" and stop only when step 4b finds nothing too.
- Start a worktree on the branch
refresh/rust-<version>, following the rules in AGENTS.md. -
Update the template files under
templates/: theeditionandrust-versionin everyCargo.toml, and anything else pinned to a version. Then update the two kinds of pin that need more than a version string:- 4a. The toolchain pins. Move
channelin the rootrust-toolchain.toml, andrust-versionin the rootCargo.toml, to the new minor release, such as1.100. Pin the template copies the way their opinion says.- The root pins name the minor release, never a patch such as
1.99.1. rustup resolves1.99to the newest 1.99 point release, so a point release arrives without an edit. - The root pins move with every release, because AGENTS.md: Scripts holds
xtask/to the repository's own opinions. Runjust clippyandjust testafter the move. A new release adds Clippy lints, and CI denies warnings. - Renovate never changes the template pins:
renovate.jsonturns the cargo manager off undertemplates/. Only this skill changes them.
- The root pins name the minor release, never a patch such as
- 4b. The crate pins in
templates/Cargo.toml. Look up every dependency on crates.io, with the API (https://crates.io/api/v1/crates/<name>, sending aUser-Agentheader) orcargo info <name>.- Take the latest stable version:
max_stable_versionin the API's answer. Never take a prerelease, or a version whoserust-versionis newer thantargets:. - Before you take a new major version, read its changelog. Before 1.0, a minor bump such as 0.12 to 0.13 is a major version, as Cargo's SemVer compatibility rules treat it. A major version that changes an idiom an opinion teaches is a content change: handle it in step 5.
- Set the
Versions verified against crates.io … on <date>comment to the run date whether or not any version changed. It's the file's only freshness record.
- Take the latest stable version:
- 4a. The toolchain pins. Move
-
Update each opinion under
opinions/:- Read the release notes from the first-party sources,
rust-blogandrust-docs: the release announcement, the release notes, and the Edition Guide. Read feature deep dives from the rest of the citable roster, such asnnethercoteon compile times orpredragon SemVer. - Add a newly stabilised feature where it changes an opinion, for example an API that replaces a crate or an old idiom.
- When a feature needs a new opinion, create a stub with a
TODOand a source link, and add itsREADME.mdScope bullet and Repository layout entry, which CI enforces. - Update
targets:andlast-reviewed:on every file you change or verify as unchanged. - Never remove or weaken a house block or region (awesome-humans/website: House opinions). If a release makes one obsolete, note inside the block that the release supersedes it, and keep the marking. A template must still build with its house regions removed.
- Read the release notes from the first-party sources,
- If a Rust toolchain is available, verify the code samples against the new targets. In
templates/, runcargo build,cargo test, andcargo clippy --all-targets -- -D warnings.- Clippy is the check a new release most often fails. A sample that still compiles can trip a lint the release added or moved into a default group.
- Treat "running 0 tests" for a crate that has tests as a failure. It means a test target stopped being built, such as a
[[test]]entry left behind by a rename. - Without a toolchain, flag the samples as unverified in the pull request.
- If the source roster changed, record it in the
AWESOME-HUMANS.mddecision log. Otherwise, summarise the run in the pull request. -
Open a pull request to the default branch, filling in the
version-refresh.mdtemplate, as AGENTS.md describes. It lists:- The versions before and after: the Rust release, the edition, and each crate pin that changed.
- The opinions that changed, and the ones verified as unchanged.
- Whether the samples built, tested, and passed Clippy.
- Anything left as a TODO.
A person reviews it before it changes any opinion.
Edge cases
- Release timing: A stable release ships every six weeks, and a new edition every three years, most recently 2024. A point release, such as 1.99.1, fixes a regression and changes no target. A run between releases that only changes
templates/Cargo.tomlis normal. - A new edition: Moving
editionis a content change, not a version bump. Runcargo fix --editionon the templates, read the Edition Guide's migration notes for each opinion, and say in the pull request what the edition changed. - An unmaintained crate: If a crate's latest stable release is much older than the current
targets:, the crate is probably unmaintained. Leave the pin, and raise it forvet-sourceor opinion review. - Guidance lags the compiler: If a feature is stable but the vetted sources haven't covered it, update the target, and keep the old idiom with a note. Don't write unsourced guidance.
- No long-term support track: Rust has none. Always target the latest stable release.