diff options
Diffstat (limited to 'docs/bootstrap-retrofit.md')
| -rw-r--r-- | docs/bootstrap-retrofit.md | 44 |
1 files changed, 36 insertions, 8 deletions
diff --git a/docs/bootstrap-retrofit.md b/docs/bootstrap-retrofit.md index 5c337e6..c099e5f 100644 --- a/docs/bootstrap-retrofit.md +++ b/docs/bootstrap-retrofit.md @@ -11,6 +11,7 @@ Migrate the repo toward the `rust-starter` posture while staying diff-aware: - preserve justified local carve-outs - delete duplicated policy only after it has been re-homed into the manifest - never paste the fresh template wholesale over a living repo +- add or preserve project-local Cargo target-dir config under `/data/main/cargo-target/<project-slug>` - add a hard source-file line cap without erasing stricter local limits or justified generated-code exemptions ## First Pass: Inventory The Existing Surfaces @@ -18,6 +19,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` +- `.cargo/config.toml` and any runner-side `--target-dir` usage - `AGENTS.md` and any nested agent instruction files - `check.py`, `xtask`, shell wrappers, `justfile`, or other runners - CI workflow files @@ -96,41 +98,65 @@ doctrine by entering the target repo, not only by invoking this bootstrap skill. Add `rust-toolchain.toml` if missing. If present but floating, pin it. -### 3. Install workspace lint tables +### 3. Install project-local Cargo target config + +Add or merge a target repo `.cargo/config.toml`: + +```toml +[build] +target-dir = "/data/main/cargo-target/<project-slug>" +``` + +Use the target repo directory name as the default slug; append a short stable +disambiguator if the basename would collide with another local repo. Preserve +unrelated Cargo config if the file already exists. + +Do not mutate user-global Cargo config during retrofit. This is an incremental +repo-local opt-in: repos without the file continue to inherit the developer's +global default. Also do not encode target-dir through runner flags or CI. If a +script currently passes `--target-dir` only to keep artifacts off the source +disk, migrate that intent into `.cargo/config.toml` and remove the flag after +the config is present. + +### 4. Install workspace lint tables Move repo-wide policy into root `[workspace.lints.*]`. -### 4. Make member crates inherit explicitly +Preserve the starter profile's wildcard/glob carve-outs unless the target repo +has a stronger explicit reason to ban them. Compact `*` imports are a house +style affordance for token economy, not a smell to suppress globally. + +### 5. Make member crates inherit explicitly Add `[lints] workspace = true` to every member crate. -### 5. Re-home script flags into the manifest +### 6. 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. -### 6. Tighten local suppression discipline +### 7. Tighten local suppression discipline Prefer: - `#[expect(..., reason = "...")]` for temporary or evidence-backed suppressions - `#[allow(..., reason = "...")]` only for stable local policy -### 7. Simplify the runner +### 8. 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. -### 8. Install the source-file cap +### 9. 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. +Default to `3000` 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. -### 9. Add deep-gate posture if the repo is ready +### 10. 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. @@ -161,8 +187,10 @@ If the repo wants CI to detect canonicalization drift rather than rewriting file - 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) +- target `.cargo/config.toml` routes Cargo output to `/data/main/cargo-target/<project-slug>` without changing user-global Cargo config - every member crate inherits that policy explicitly - scripts and CI no longer restate Clippy allowlists +- scripts, CI, and manifest-owned command vectors do not pass `--target-dir` - manifest-owned canonicalization exists where the repo wants auto-fixes, instead of living in shell aliases or tribal memory - valid repo-specific exceptions remain intact and justified - stricter pre-existing rules remain stricter |