From f9f897b32cad3bf10fcc06774887254922eaea74 Mon Sep 17 00:00:00 2001 From: main Date: Sun, 14 Jun 2026 23:49:59 -0400 Subject: Scrub hardcoded Rust toolchain defaults Teach rust-bootstrap to use the latest system Rust toolchain, derive rust-version only from active rustc when needed, and initialize Git before applying the fresh template in an empty directory. --- docs/rust-linting-proposal.md | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) (limited to 'docs/rust-linting-proposal.md') diff --git a/docs/rust-linting-proposal.md b/docs/rust-linting-proposal.md index ba5b5cf..64c90fa 100644 --- a/docs/rust-linting-proposal.md +++ b/docs/rust-linting-proposal.md @@ -14,7 +14,7 @@ The best current design is: 3. Keep the runner orchestration-only: source-file cap, `fmt --check`, `clippy`, tests, then optional deeper gates. 4. Check in project-local Cargo target-dir config so opted-in repos build under `/data/main/cargo-target/`. -5. Pin an exact stable toolchain so lint drift is a conscious upgrade event. +5. Use the latest system Rust toolchain; never copy a hardcoded Rust version from the starter. 6. Centralize repo-wide Clippy carve-outs and structural thresholds in the root manifest, and force local suppressions to carry reasons. The local corpus already converges on this. The newer `adequate_*`, `memcp`, `outpost`, and `picmash` workspaces are structurally superior to the older `check.py` / shell-script pattern because they put policy in manifest tables instead of command-line tails. @@ -146,24 +146,26 @@ Clippy’s usage docs are explicit here: `--no-deps` is for linting only a selec That is useful for a narrow crate-local loop, but it is the wrong default for a workspace-wide industrial gate. The starter profile should lint the whole workspace, not silently skip member crates that happen to be path dependencies. -### 6. `rust-version` is part of lint policy +### 6. `rust-version` must come from the system toolchain, not the template Clippy uses the crate’s MSRV configuration, and the docs note that it defaults to the `rust-version` field in `Cargo.toml`. Implication: -- every starter-pack workspace should set `rust-version` -- the field should reflect the actual supported minimum, not a decorative guess +- if a starter-pack workspace sets `rust-version`, derive it from the active system `rustc --version` +- do not preserve a hardcoded Rust version in the starter template +- do not invent an MSRV unless the target repo has an explicit external compatibility constraint -### 7. Pinned toolchains are part of the enforcement story +### 7. The latest system toolchain is part of the enforcement story The rustup toolchain file supports exact channels, components, profile, and targets. For strict linting, that matters because Clippy output changes over time. Implication: -- pin an exact stable patch release in `rust-toolchain.toml` -- include `clippy` and `rustfmt` -- prefer `profile = "minimal"` unless the repo has a real reason not to +- inspect `rustc --version` and `cargo --version` during bootstrap and retrofit +- use the latest toolchain already selected by the system +- include `clippy` and `rustfmt` when a rustup-managed target writes `rust-toolchain.toml` +- do not encode a stale numeric toolchain in the starter template ### 8. `unexpected_cfgs` plus `check-cfg` is one of the highest-value newer strengthenings @@ -212,7 +214,6 @@ resolver = "3" [workspace.package] edition = "2024" -rust-version = "1.xx" version = "0.1.0" [workspace.lints.rust] @@ -377,12 +378,16 @@ Check in a `rust-toolchain.toml` like: ```toml [toolchain] -channel = "1.xx.0" +channel = "stable" profile = "minimal" components = ["clippy", "rustfmt"] ``` -Use an exact stable patch at scaffold time and bump it deliberately. Do not float on `"stable"` if the goal is reproducible strictness. +Use the latest system Rust toolchain. The template deliberately avoids a +numbered channel because stale examples become silent policy. If the target +repo records `rust-version`, derive it from the active system `rustc --version`; +if the target environment does not use rustup, omit `rust-toolchain.toml` rather +than fabricating a pin. ### 4. Exception policy @@ -517,7 +522,9 @@ If the repo publishes libraries, add `cargo semver-checks` to the deeper release #### Periodic canary job -Run a scheduled CI job against the latest stable toolchain without updating the pinned toolchain file. Let it warn, not block merges. That gives early visibility into upcoming Clippy churn while preserving deterministic mainline CI. +Run a scheduled CI job after system toolchain updates. Let it warn, not block +merges. That gives early visibility into upcoming Clippy churn without +tempting the starter to carry a stale Rust version. ## Choices I Reject @@ -547,21 +554,22 @@ It is useful as a canary or opt-in experiment, not as the default industrial pro Not until Cargo’s own lint namespace stabilizes. -### Floating toolchains in strict CI +### Copying a hardcoded Rust version from the starter -If the goal is "force industrial-grade linting", ambient toolchain drift is the enemy. +If the goal is "force industrial-grade linting", a stale template version is +the enemy. Inspect the active system toolchain and use that. ## Proposed AGENTS.md One-Liner Use this style: -> Set up Rust linting with the `rust-starter` industrial profile: link target `AGENTS.md` to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md); install project-local `.cargo/config.toml` with `[build] target-dir = "/data/main/cargo-target/"` without changing user-global Cargo config; pin an exact stable `rust-toolchain.toml`; put repo policy only in root `[workspace.lints.{rust,rustdoc,clippy}]` plus manifest-owned canonicalization and verification command vectors and source-file-cap metadata in `workspace.metadata`; make every crate opt into `[lints] workspace = true`; make the default local `check` path canonicalize first, but keep a non-mutating `verify` path for CI; cherry-pick restriction bans instead of enabling `clippy::restriction`; keep repo-wide Clippy carve-outs centralized and commented in `Cargo.toml`; and require local suppressions to use `#[expect(..., reason = "...")]` unless a permanent `#[allow(..., reason = "...")]` is truly justified. +> Set up Rust linting with the `rust-starter` industrial profile: link target `AGENTS.md` to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md); run `git init` first when bootstrapping an empty target directory; use the latest system Rust toolchain and never copy a hardcoded Rust version from the starter; install project-local `.cargo/config.toml` with `[build] target-dir = "/data/main/cargo-target/"` without changing user-global Cargo config; put repo policy only in root `[workspace.lints.{rust,rustdoc,clippy}]` plus manifest-owned canonicalization and verification command vectors and source-file-cap metadata in `workspace.metadata`; make every crate opt into `[lints] workspace = true`; make the default local `check` path canonicalize first, but keep a non-mutating `verify` path for CI; cherry-pick restriction bans instead of enabling `clippy::restriction`; keep repo-wide Clippy carve-outs centralized and commented in `Cargo.toml`; and require local suppressions to use `#[expect(..., reason = "...")]` unless a permanent `#[allow(..., reason = "...")]` is truly justified. That is long, but it is precise and inferable by a model. ## Bottom Line -The starter pack should standardize the newer Cargo-centric pattern already emerging locally, add repo-local Cargo target-dir config for `/data/main/cargo-target/`, harden it with toolchain pinning, distinguish manifest-owned policy from runner orchestration, export a first-class canonicalization pipeline, enforce a manifest-backed hard source-file cap, tighten suppression discipline with `reason = "..."`, and add an optional deeper gate for feature matrices, docs, dependency hygiene, and public API drift. +The starter pack should standardize the newer Cargo-centric pattern already emerging locally, initialize Git for empty fresh targets, use the latest system Rust toolchain instead of stale template versions, add repo-local Cargo target-dir config for `/data/main/cargo-target/`, distinguish manifest-owned policy from runner orchestration, export a first-class canonicalization pipeline, enforce a manifest-backed hard source-file cap, tighten suppression discipline with `reason = "..."`, and add an optional deeper gate for feature matrices, docs, dependency hygiene, and public API drift. The single strongest improvement over the current local state is not any one lint. It is moving the center of gravity from bespoke scripts to manifest-owned policy. -- cgit v1.2.3