From c927ac1c6e041f96326e4a32e76ca13da8f6f5be Mon Sep 17 00:00:00 2001 From: main Date: Tue, 31 Mar 2026 14:21:52 -0400 Subject: Initial import --- docs/bootstrap-fresh.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/bootstrap-fresh.md (limited to 'docs/bootstrap-fresh.md') diff --git a/docs/bootstrap-fresh.md b/docs/bootstrap-fresh.md new file mode 100644 index 0000000..f77b819 --- /dev/null +++ b/docs/bootstrap-fresh.md @@ -0,0 +1,128 @@ +# Fresh Bootstrap + +Use this surface when the target repo is blank or when you are setting up Rust linting from scratch. + +## Goal + +Install the `rust-starter` lint posture cleanly: + +- root `Cargo.toml` owns lint levels +- every crate inherits workspace lint policy +- `rust-toolchain.toml` is pinned exactly +- `clippy.toml` stays tiny and only carries structured config +- the runner stays thin and reads canonicalization and verification command vectors plus the source-file cap from workspace metadata instead of restating policy + +## Inputs To Set Deliberately + +Before copying the template, decide: + +- actual workspace members +- package naming +- license policy +- exact pinned stable toolchain +- actual MSRV / `rust-version` +- whether tests should allow `expect`, `unwrap`, or `panic` +- whether the repo is library-heavy enough to keep rustdoc linting in the fast gate or only the deep gate +- whether unsafe Rust is forbidden or tightly-governed +- whether the default `2500`-line source-file cap should stay as-is or be tightened for this repo + +## Files To Start From + +Use these as the concrete baseline: + +- [template/fresh/Cargo.toml](/home/main/programming/projects/rust_starter/template/fresh/Cargo.toml) +- [template/fresh/rust-toolchain.toml](/home/main/programming/projects/rust_starter/template/fresh/rust-toolchain.toml) +- [template/fresh/clippy.toml](/home/main/programming/projects/rust_starter/template/fresh/clippy.toml) +- [template/fresh/check.py](/home/main/programming/projects/rust_starter/template/fresh/check.py) +- [template/fresh/crates/app/Cargo.toml](/home/main/programming/projects/rust_starter/template/fresh/crates/app/Cargo.toml) +- [template/fresh/crates/app/src/main.rs](/home/main/programming/projects/rust_starter/template/fresh/crates/app/src/main.rs) + +Do not copy them mechanically. Replace the placeholder members, names, license, and version/toolchain values. + +## Sequence + +### 1. Write the root manifest first + +Start from the template root manifest and adapt: + +- workspace member list +- package metadata +- pinned `rust-version` +- repo-wide Clippy carve-outs + +Keep the command vectors in `[workspace.metadata.rust-starter]` even if you later wrap them with a different local runner. + +The fresh template exports an ordered `canonicalize_commands` pipeline. Keep it repo-owned in the root manifest and make the default `check` path run it automatically before the verification gate so humans and agents do not need to remember a separate pre-pass. + +Also keep the source-file cap in `[workspace.metadata.rust-starter.source_files]`. The starter default is a hard `2500`-line limit across `*.rs` files. Tighten it if the repo already has sharper discipline. + +### 2. Pin the toolchain second + +Write `rust-toolchain.toml` early, before deciding whether a lint is noisy or broken. Lint output is part of the toolchain contract. + +### 3. Make every crate inherit lint policy + +Each member crate must contain: + +```toml +[lints] +workspace = true +``` + +Do not rely on memory or convention here; add it explicitly. + +### 4. Add `clippy.toml` only if it carries real configuration + +The default template only relaxes `expect`, `unwrap`, and `panic` inside tests. If the target repo does not want that, delete the file instead of leaving inert config behind. + +Do not move global allow/deny policy into `clippy.toml`. + +### 5. Add a thin runner + +The template `check.py` is intentionally small. It reads canonicalization and verification commands plus the source-file policy from workspace metadata, enforces the file cap, and then runs the Rust commands. + +Default runner shape: + +- `check`: enforce the file cap, run canonicalization, then verify formatting, lint, and tests +- `verify`: enforce the file cap without mutating files; this is the non-writing CI-friendly path +- `deep`: `check` plus docs +- `fix` / `canon`: canonicalization only + +If the target repo already prefers another orchestration surface, keep that surface only if it remains policy-thin: + +- okay: `xtask`, `just`, shell wrapper, CI job that calls the canonical commands +- not okay: restating dozens of `-A` and `-D` flags in scripts + +If the repo has checked-in generated Rust that should not count against the cap, express that with explicit `exclude` patterns under `[workspace.metadata.rust-starter.source_files]` instead of weakening the global limit. + +### 6. Keep the deep gate opt-in + +The template only installs the fast gate. Add the deeper posture when the repo is mature enough: + +- `cargo hack clippy --workspace --all-targets --feature-powerset` +- `cargo hack test --workspace --feature-powerset` +- `cargo doc --workspace --all-features --no-deps` +- `cargo deny check` +- optionally `cargo nextest` and `cargo semver-checks` + +## Do Not Do These + +- do not use `--no-deps` as the workspace-wide Clippy default +- do not enable `clippy::restriction` wholesale +- do not enable `clippy::nursery` wholesale +- do not duplicate lint policy in scripts, CI, and editor config +- do not leave placeholder toolchain or MSRV values unreviewed + +## Acceptance Checklist + +- root `Cargo.toml` contains `[workspace.lints.rust]`, `[workspace.lints.rustdoc]`, and `[workspace.lints.clippy]` +- root `Cargo.toml` contains canonical command vectors in `[workspace.metadata.rust-starter]` +- root `Cargo.toml` contains an ordered `canonicalize_commands` pipeline in `[workspace.metadata.rust-starter]` +- root `Cargo.toml` contains `[workspace.metadata.rust-starter.source_files]` with an intentional `max_lines` value +- each member crate opts into `[lints] workspace = true` +- `rust-toolchain.toml` pins an exact stable patch and includes `clippy` plus `rustfmt` +- `clippy.toml` is either tiny and justified or absent +- the default `check` path canonicalizes before verification, and a non-mutating `verify` path exists for CI or drift detection +- no runner or CI file duplicates the Clippy allowlist + +Read [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md) only when you need rationale or policy nuance. -- cgit v1.2.3