diff options
Diffstat (limited to 'docs/bootstrap-retrofit.md')
| -rw-r--r-- | docs/bootstrap-retrofit.md | 29 |
1 files changed, 21 insertions, 8 deletions
diff --git a/docs/bootstrap-retrofit.md b/docs/bootstrap-retrofit.md index a2910ce..5c337e6 100644 --- a/docs/bootstrap-retrofit.md +++ b/docs/bootstrap-retrofit.md @@ -6,6 +6,7 @@ Use this surface when the target repo already has Rust linting, but you want to Migrate the repo toward the `rust-starter` posture while staying diff-aware: +- install the canonical Rust style doctrine link in target `AGENTS.md` - preserve stricter existing rules - preserve justified local carve-outs - delete duplicated policy only after it has been re-homed into the manifest @@ -17,6 +18,7 @@ Migrate the repo toward the `rust-starter` posture while staying diff-aware: Before editing, inspect all of the places the repo may already encode lint policy: - root and member `Cargo.toml` +- `AGENTS.md` and any nested agent instruction files - `check.py`, `xtask`, shell wrappers, `justfile`, or other runners - CI workflow files - any existing auto-fix or canonicalization commands @@ -36,6 +38,7 @@ Use these as the baseline, not as paste targets: - [template/fresh](/home/main/programming/projects/rust_starter/template/fresh) - [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md) +- [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md) The fresh template tells you the shape to converge toward. The proposal doc tells you why. @@ -80,45 +83,54 @@ Keep `clippy.toml` only for structured knobs such as test allowances. Apply tightenings in this order: -### 1. Pin or refresh the toolchain +### 1. Install style inheritance + +Add or preserve a target `AGENTS.md` link to +[docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md). +Do not overwrite local agent instructions; merge the doctrine link into them. + +This is intentionally infectious. Future agents should read the Rust style +doctrine by entering the target repo, not only by invoking this bootstrap skill. + +### 2. Pin or refresh the toolchain Add `rust-toolchain.toml` if missing. If present but floating, pin it. -### 2. Install workspace lint tables +### 3. Install workspace lint tables Move repo-wide policy into root `[workspace.lints.*]`. -### 3. Make member crates inherit explicitly +### 4. Make member crates inherit explicitly Add `[lints] workspace = true` to every member crate. -### 4. Re-home script flags into the manifest +### 5. Re-home script flags into the manifest Take inline `cargo clippy -- -A/-D ...` tails from scripts and CI, and migrate them into the root manifest in grouped, commented form. That includes `-D warnings`: if warnings are meant to be fatal, encode that as `warnings = "deny"` under `[workspace.lints.rust]` instead of leaving it as a command-line tail. -### 5. Tighten local suppression discipline +### 6. Tighten local suppression discipline Prefer: - `#[expect(..., reason = "...")]` for temporary or evidence-backed suppressions - `#[allow(..., reason = "...")]` only for stable local policy -### 6. Simplify the runner +### 7. Simplify the runner Once the manifest is authoritative, collapse the runner to orchestration-only plus generic manifest-backed checks such as the source-file cap. If the repo already has an auto-fix pass, re-home it into root `workspace.metadata.rust-starter.canonicalize_commands` and make the default local `check` path invoke it before the verification gate instead of relying on engineers or agents to remember a separate pre-pass. -### 7. Install the source-file cap +### 8. Install the source-file cap Add `[workspace.metadata.rust-starter.source_files]` to the root manifest and set `max_lines` deliberately. Default to `2500` if the repo has no existing stance. If the repo already enforces a stricter cap, keep the stricter value. If the repo has checked-in generated Rust that would make the rule meaningless, exclude those paths explicitly instead of disabling the whole mechanism. -### 8. Add deep-gate posture if the repo is ready +### 9. Add deep-gate posture if the repo is ready Add `cargo hack`, docs, and dependency-hygiene checks only when the repo can support them without turning the whole effort into churn theater. @@ -148,6 +160,7 @@ If the repo wants CI to detect canonicalization drift rather than rewriting file ## Acceptance Checklist - repo-wide policy lives in root `[workspace.lints.*]` +- target `AGENTS.md` links to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md) - every member crate inherits that policy explicitly - scripts and CI no longer restate Clippy allowlists - manifest-owned canonicalization exists where the repo wants auto-fixes, instead of living in shell aliases or tribal memory |