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. It's the cue to run this skill. - Never commit to
automation/rust-release-watch. Untilmainhas the new snapshot, each run of the workflow rebuilds that branch frommainand force-pushes it, so a commit there is lost. - The skill works on its own branch, which step 3 starts, and copies the snapshot there. The refresh pull request then merges the snapshot and the update together, and step 8 closes the trigger pull request.
- You can also run the skill by itself. The snapshot answers "Which stable release does this repository know about?" offline.
Orchestration
As agents/orchestration.md 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.
- If you stop here while a trigger pull request is open, check that its snapshot names the release step 1 found, and say that it can merge as it is. It holds only the snapshot, and nothing else lands it on
main. If the snapshot names a newer release, run steps 1 and 2 again for that release.
- Start a worktree from
mainon the branchrefresh/rust-<version>, following the rules in agents/worktrees.md.- To find an open trigger pull request, run
gh pr list --label rust-release --state open. A leftoverautomation/rust-release-watchbranch without one isn't a trigger. - If one is open, copy its snapshot into the worktree: run
git fetch origin automation/rust-release-watch, thengit restore --source=FETCH_HEAD -- .github/state/rust-releases.json. Commit it with the rest of the run. - If that snapshot is older than the release step 1 found, run the workflow first, with
gh workflow run rust-release-watch.yml, and copy the snapshot once it finishes. If it's newer, a release shipped after step 1 ran: run steps 1 and 2 again for that release. - Without a trigger pull request, leave the snapshot alone. Only the workflow writes it. The trigger pull request it opens later holds only the snapshot. It can merge as it is once the refresh pull request has merged, and not before: with the snapshot on
mainand no refresh, the workflow opens no further trigger for that release.
- To find an open trigger pull request, run
-
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/checks.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 detailed posts on each feature 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. Run
just build-templates, which copiestemplates/into a workspace undertarget/templates/and runscargo build,cargo test,CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets, andcargo fmt --checkon it. The recipe checks only the templates. To check an opinion's sample, add it to the copy the recipe leaves intarget/templates/none/, and run the same four commands there.- 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/maintaining.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.
If the run copied a trigger pull request's snapshot, end the description with a
Refs: #<number>trailer for it, and comment on the trigger pull request with the refresh pull request's number. The comment says to close the trigger pull request once the refresh merges.After the refresh pull request merges, close the trigger pull request, if it's still open, with
gh pr close <number> --delete-branch. The workflow never closes it: once the snapshot onmainmatches the manifest, the workflow skips its pull request step. If the trigger pull request's snapshot differs from the one onmainby then, a newer release has arrived. Leave it open as the cue for the next run.
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.