diff options
Diffstat (limited to 'docs/bootstrap-fresh.md')
| -rw-r--r-- | docs/bootstrap-fresh.md | 49 |
1 files changed, 33 insertions, 16 deletions
diff --git a/docs/bootstrap-fresh.md b/docs/bootstrap-fresh.md index b3c9112..2db3ccc 100644 --- a/docs/bootstrap-fresh.md +++ b/docs/bootstrap-fresh.md @@ -9,7 +9,7 @@ Install the `rust-starter` lint posture cleanly: - target `AGENTS.md` links to the canonical Rust style doctrine - root `Cargo.toml` owns lint levels - every crate inherits workspace lint policy -- `rust-toolchain.toml` is pinned exactly +- the latest system Rust toolchain is used instead of a hardcoded starter version - project-local `.cargo/config.toml` routes Cargo output to `/data/main/cargo-target/<project-slug>` - `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 @@ -21,8 +21,8 @@ Before copying the template, decide: - actual workspace members - package naming - license policy -- exact pinned stable toolchain -- actual MSRV / `rust-version` +- active system Rust toolchain from `rustc --version` and `cargo --version` +- whether the target should record a `rust-version`; if so, derive it from the active system `rustc` - Cargo target-dir slug under `/data/main/cargo-target`, normally the target repo directory name - 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 @@ -44,11 +44,17 @@ Use these as the concrete baseline: - [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, Cargo target-dir slug, and version/toolchain values. +Do not copy them mechanically. Replace the placeholder members, names, license, and Cargo target-dir slug. Do not copy a Rust version from the starter; inspect the active system toolchain. ## Sequence -### 1. Seed `AGENTS.md` first +### 1. Initialize Git for an empty target + +If the target directory is empty and is not already inside a Git worktree, run +`git init` before copying template files. The starter assumes normal versioned +Rust work; beginning from an unversioned empty directory is gratuitous entropy. + +### 2. Seed `AGENTS.md` Create or adapt the target repo's `AGENTS.md` so it links to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md). @@ -59,22 +65,25 @@ merge the link without erasing local rules. The point is inheritance: future agents entering the repo must encounter the Rust style doctrine without knowing this bootstrap skill exists. -### 2. Write the root manifest +### 3. Write the root manifest Start from the template root manifest and adapt: - workspace member list - package metadata -- pinned `rust-version` - repo-wide Clippy carve-outs +If the target records `workspace.package.rust-version`, derive it from the +active system `rustc --version`; do not invent a minimum supported Rust version +from memory and do not paste one from this starter. + 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 `3000`-line limit across `*.rs` files. Tighten it if the repo already has sharper discipline. -### 3. Install project-local Cargo target config +### 4. Install project-local Cargo target config Create or adapt the target repo's `.cargo/config.toml` before running Cargo commands: @@ -96,11 +105,18 @@ remains the fallback. If `.cargo/config.toml` already exists, merge the `[build] target-dir` value without overwriting unrelated Cargo configuration. -### 4. Pin the toolchain +### 5. Use the latest system Rust toolchain + +Inspect `rustc --version` and `cargo --version` early, before deciding whether a +lint is noisy or broken. Lint output is part of the toolchain contract, and the +contract here is the latest Rust toolchain already selected by the system. -Write `rust-toolchain.toml` early, before deciding whether a lint is noisy or broken. Lint output is part of the toolchain contract. +The template `rust-toolchain.toml` deliberately avoids a numbered channel. Do +not replace it with a remembered version. If the target repo needs a rustup +override, use the active system toolchain; if the target environment does not +use rustup, omit the file rather than fabricating a pin. -### 5. Make every crate inherit lint policy +### 6. Make every crate inherit lint policy Each member crate must contain: @@ -111,13 +127,13 @@ workspace = true Do not rely on memory or convention here; add it explicitly. -### 6. Add `clippy.toml` only if it carries real configuration +### 7. 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`. -### 7. Add a thin runner +### 8. 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. @@ -135,7 +151,7 @@ If the target repo already prefers another orchestration surface, keep that surf 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. -### 8. Keep the deep gate opt-in +### 9. Keep the deep gate opt-in The template only installs the fast gate. Add the deeper posture when the repo is mature enough: @@ -153,20 +169,21 @@ The template only installs the fast gate. Add the deeper posture when the repo i - do not duplicate lint policy in scripts, CI, and editor config - do not pass `--target-dir` from runners, CI, or command vectors; use `.cargo/config.toml` - do not change user-global Cargo config as part of bootstrapping a target repo -- do not leave placeholder toolchain or MSRV values unreviewed +- do not hardcode a Rust version from the starter or from memory ## Acceptance Checklist - root `Cargo.toml` contains `[workspace.lints.rust]`, `[workspace.lints.rustdoc]`, and `[workspace.lints.clippy]` - 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` contains `[build] target-dir = "/data/main/cargo-target/<project-slug>"` +- fresh bootstraps in an empty target directory start with `git init` - root `Cargo.toml` owns warning-fatality policy, e.g. `warnings = "deny"` under `[workspace.lints.rust]`, rather than hiding it in runner flags - root `Cargo.toml` preserves the global wildcard/glob carve-outs; compact `*` imports are intentionally allowed for token economy - 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` +- the target uses the latest system Rust toolchain; any `rust-version` value is derived from the active system `rustc` - `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 |