From 2ddf8f9e4bceba684e6bdcc45647970ce9aedb1c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 12:41:03 +0000 Subject: [PATCH 01/11] docs: add contributing guide and AI instruction files https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- .github/copilot-instructions.md | 16 +++ CLAUDE.md | 16 +++ CONTRIBUTING.md | 189 ++++++++++++++++++++++++++++++++ 3 files changed, 221 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..19ff306c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,16 @@ +# GitHub Copilot Instructions + +Read and follow the CONTRIBUTING.md file in this repository for all code style conventions, commit message format, and development guidelines. + +## Quick Reference + +- Commit format: Conventional Commits — `type(scope): lowercase description` +- Version releases are the only exception: just the version number (e.g. `0.21.1`) +- Import order: internal (`crate::`/`super::`) → external crates → `std::` +- Use descriptive generic names (`Size`, `Report`), not single letters +- Prefer `where` clauses for multiple trait bounds +- Derive order: std traits → comparison traits → derive_more → feature-gated +- Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` +- No `unwrap()` — use proper error handling +- `#![deny(warnings)]` is active — code must be warning-free +- Run `FMT=true LINT=true BUILD=true TEST=true ./test.sh` to validate changes diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..ec8d0c91 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,16 @@ +# Claude Code Instructions + +Read and follow the CONTRIBUTING.md file in this repository for all code style conventions, commit message format, and development guidelines. + +## Quick Reference + +- Commit format: Conventional Commits — `type(scope): lowercase description` +- Version releases are the only exception: just the version number (e.g. `0.21.1`) +- Import order: internal (`crate::`/`super::`) → external crates → `std::` +- Use descriptive generic names (`Size`, `Report`), not single letters +- Prefer `where` clauses for multiple trait bounds +- Derive order: std traits → comparison traits → derive_more → feature-gated +- Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` +- No `unwrap()` — use proper error handling +- `#![deny(warnings)]` is active — code must be warning-free +- Run `FMT=true LINT=true BUILD=true TEST=true ./test.sh` to validate changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b04220ad --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,189 @@ +# Contributing to parallel-disk-usage + +## Commit Message Convention + +This project uses [Conventional Commits](https://www.conventionalcommits.org/). + +### Format + +``` +type(scope): lowercase description +``` + +### Rules + +- **Types:** `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `chore`, `ci`, `test`, `lint` +- **Scopes** (optional): `cli`, `api`, `deps`, `readme`, `benchmark`, `toolchain`, `test`, or other relevant area +- **Description:** always lowercase after the colon, no trailing period, brief (3-7 words preferred) +- **Breaking changes:** append `!` before the colon (e.g. `feat(cli)!: remove deprecated flag`) +- **Code identifiers** in descriptions should be wrapped in backticks (e.g. `` chore(deps): update `rand` ``) + +### Exception: Version Releases + +Version release commits use **only** the version number as the message — no type prefix: + +``` +0.21.1 +``` + +## Code Style + +Automated tools enforce formatting (`cargo fmt`) and linting (`cargo clippy`). The following conventions are **not** enforced by those tools and must be followed manually. + +### Import Organization + +Imports are grouped in this order, separated by blank lines: + +1. `use super::...` or `use crate::...` (internal) +2. External crate imports (alphabetical) +3. `use std::...` (standard library) + +Within each group, items are ordered alphabetically. Platform-specific imports (`#[cfg(unix)]`) go in a separate block after the main imports. + +```rust +use crate::{ + args::{Args, Quantity, Threads}, + bytes_format::BytesFormat, + size, +}; +use clap::Parser; +use pipe_trait::Pipe; +use std::{io::stdin, time::Duration}; + +#[cfg(unix)] +use crate::get_size::{GetBlockCount, GetBlockSize}; +``` + +### Module Organization + +- Use the flat file pattern (`module.rs`) rather than `module/mod.rs` for submodules. +- List `pub mod` declarations first, then `pub use` re-exports, then private imports and items. +- Use `pub use` to re-export key types at the module level for convenience. + +```rust +pub mod error_only_reporter; +pub mod error_report; +pub mod event; + +pub use error_only_reporter::ErrorOnlyReporter; +pub use error_report::ErrorReport; +pub use event::Event; +``` + +- Type aliases using `pub use ... as ...` are used to provide semantic alternative names: + +```rust +pub use Reflection as DataTreeReflection; +``` + +### Derive Macro Ordering + +When deriving multiple traits, use this order and split across multiple `#[derive(...)]` lines for readability: + +1. **Standard traits:** `Debug`, `Default`, `Clone`, `Copy` +2. **Comparison traits:** `PartialEq`, `Eq`, `PartialOrd`, `Ord` +3. **Hash** +4. **`derive_more` traits:** `Display`, `From`, `Into`, `Add`, `AddAssign`, etc. +5. **Feature-gated derives** on a separate `#[cfg_attr(...)]` line + +```rust +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +#[derive(From, Into, Add, AddAssign, Sub, SubAssign, Sum)] +#[cfg_attr(feature = "json", derive(Deserialize, Serialize))] +pub struct Bytes(u64); +``` + +### Generic Parameter Naming + +Use **descriptive names** for type parameters, not single letters: + +- `Size`, `Name`, `SizeGetter`, `HardlinksRecorder`, `Report` + +Single-letter generics are acceptable only in very short, self-contained trait impls. + +### Trait Bounds + +Prefer `where` clauses over inline bounds when there are multiple constraints: + +```rust +impl + From> + for DataTree +where + Report: Reporter + Sync + ?Sized, + Size: size::Size + Send + Sync, + SizeGetter: GetSize + Sync, + HardlinksRecorder: RecordHardlinks + Sync + ?Sized, +``` + +### Visibility + +- Use `pub` for the public API surface. +- Use `pub(crate)` for items shared within the crate but not exposed externally. +- Default to private for everything else. + +### Error Handling + +- Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`. +- Mark error enums as `#[non_exhaustive]`. +- Avoid `unwrap()` — use proper error propagation. When deliberately ignoring an error, use `.ok()` with a comment explaining why. + +```rust +#[derive(Debug, Display, Error)] +#[non_exhaustive] +pub enum RuntimeError { + #[display("SerializationFailure: {_0}")] + SerializationFailure(serde_json::Error), +} +``` + +### Documentation Comments + +- Use `///` doc comments for all public types, traits, functions, and fields. +- Use `//!` module-level doc comments at the top of `lib.rs` and significant modules. +- Include usage examples with `/// ```no_run` blocks for key public APIs. +- Reference related types with `[`backtick links`](crate::path)` syntax. + +### Feature Gating + +- Use `#[cfg(feature = "...")]` for optional functionality (e.g., `json`, `cli`). +- Use `#[cfg(unix)]` for POSIX-specific code. +- Use `#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]` for conditional derives. + +### Pattern Matching + +Use exhaustive matching. When mapping enum variants to values, prefer the concise wrapping style: + +```rust +ExitCode::from(match self { + RuntimeError::SerializationFailure(_) => 2, + RuntimeError::DeserializationFailure(_) => 3, +}) +``` + +### Struct Field Ordering + +Order fields logically by purpose, not alphabetically. Group related fields together. Document every public field with `///` comments. + +### Macros + +Use macros to reduce boilerplate for repetitive patterns (e.g. newtype wrappers, trait impls for multiple numeric types). Keep macros well-scoped and documented. + +### Warnings Policy + +The crate uses `#![deny(warnings)]` — all warnings are treated as errors. Code must compile warning-free. + +## Automated Checks + +Before submitting, ensure: + +- `cargo fmt -- --check` passes +- `cargo clippy` passes (on all feature combinations) +- `cargo test` passes +- The project builds with no default features, default features, and all features + +The CI script `test.sh` runs all of these across 5 feature combinations. You can run it locally with: + +```sh +FMT=true LINT=true BUILD=true TEST=true ./test.sh +``` From 961dfa20f1913e5057c3ecc3bad7c39fa299f113 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 13:10:50 +0000 Subject: [PATCH 02/11] docs: add `AGENTS.md` for Codex compatibility https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- AGENTS.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..50ebf64c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# AI Agent Instructions + +Read and follow the CONTRIBUTING.md file in this repository for all code style conventions, commit message format, and development guidelines. + +## Quick Reference + +- Commit format: Conventional Commits — `type(scope): lowercase description` +- Version releases are the only exception: just the version number (e.g. `0.21.1`) +- Import order: internal (`crate::`/`super::`) → external crates → `std::` +- Use descriptive generic names (`Size`, `Report`), not single letters +- Prefer `where` clauses for multiple trait bounds +- Derive order: std traits → comparison traits → derive_more → feature-gated +- Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` +- No `unwrap()` — use proper error handling +- `#![deny(warnings)]` is active — code must be warning-free +- Run `FMT=true LINT=true BUILD=true TEST=true ./test.sh` to validate changes From 2db49b1bebb7f05505215c01710770e1058ea3e9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 13:16:46 +0000 Subject: [PATCH 03/11] test: add sync check for AI instruction files Ensures CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md stay in sync (identical content after the title line). https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- tests/sync_ai_instructions.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 tests/sync_ai_instructions.rs diff --git a/tests/sync_ai_instructions.rs b/tests/sync_ai_instructions.rs new file mode 100644 index 00000000..750d1252 --- /dev/null +++ b/tests/sync_ai_instructions.rs @@ -0,0 +1,33 @@ +//! The following tests check whether the AI instruction files are in sync. +//! +//! All three files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) should have +//! identical content (except for the title line). + +macro_rules! check { + ($name:ident: $a_path:literal == $b_path:literal) => { + #[test] + fn $name() { + let a = include_str!($a_path); + let b = include_str!($b_path); + let a_body = strip_title(a); + let b_body = strip_title(b); + assert!( + a_body == b_body, + concat!( + "AI instruction files are out of sync: ", + $a_path, + " != ", + $b_path, + ), + ); + } + }; +} + +/// Strip the first line (title) and return the rest. +fn strip_title(text: &str) -> &str { + text.split_once('\n').map_or("", |(_, rest)| rest) +} + +check!(claude_md_vs_agents_md: "../CLAUDE.md" == "../AGENTS.md"); +check!(claude_md_vs_copilot_instructions: "../CLAUDE.md" == "../.github/copilot-instructions.md"); From d3636c8a52ea8fe09024040240c76399d9b4bbd3 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 13:34:32 +0000 Subject: [PATCH 04/11] docs: address PR review feedback - Add `Hash` to derive order in quick reference (all AI instruction files) - Add `DOC=true` to the test command in CONTRIBUTING.md and AI instruction files - Clarify `unwrap()` rule: acceptable in tests and provably infallible operations - Unify titles to "AI Instructions" across all three files - Simplify sync test by removing `strip_title` (titles are now identical) https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- .github/copilot-instructions.md | 6 +++--- AGENTS.md | 6 +++--- CLAUDE.md | 6 +++--- CONTRIBUTING.md | 4 ++-- tests/sync_ai_instructions.rs | 12 ++---------- 5 files changed, 13 insertions(+), 21 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 19ff306c..059ce3ae 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,4 +1,4 @@ -# GitHub Copilot Instructions +# AI Instructions Read and follow the CONTRIBUTING.md file in this repository for all code style conventions, commit message format, and development guidelines. @@ -9,8 +9,8 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Import order: internal (`crate::`/`super::`) → external crates → `std::` - Use descriptive generic names (`Size`, `Report`), not single letters - Prefer `where` clauses for multiple trait bounds -- Derive order: std traits → comparison traits → derive_more → feature-gated +- Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - No `unwrap()` — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free -- Run `FMT=true LINT=true BUILD=true TEST=true ./test.sh` to validate changes +- Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/AGENTS.md b/AGENTS.md index 50ebf64c..059ce3ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# AI Agent Instructions +# AI Instructions Read and follow the CONTRIBUTING.md file in this repository for all code style conventions, commit message format, and development guidelines. @@ -9,8 +9,8 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Import order: internal (`crate::`/`super::`) → external crates → `std::` - Use descriptive generic names (`Size`, `Report`), not single letters - Prefer `where` clauses for multiple trait bounds -- Derive order: std traits → comparison traits → derive_more → feature-gated +- Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - No `unwrap()` — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free -- Run `FMT=true LINT=true BUILD=true TEST=true ./test.sh` to validate changes +- Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CLAUDE.md b/CLAUDE.md index ec8d0c91..059ce3ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# Claude Code Instructions +# AI Instructions Read and follow the CONTRIBUTING.md file in this repository for all code style conventions, commit message format, and development guidelines. @@ -9,8 +9,8 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Import order: internal (`crate::`/`super::`) → external crates → `std::` - Use descriptive generic names (`Size`, `Report`), not single letters - Prefer `where` clauses for multiple trait bounds -- Derive order: std traits → comparison traits → derive_more → feature-gated +- Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - No `unwrap()` — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free -- Run `FMT=true LINT=true BUILD=true TEST=true ./test.sh` to validate changes +- Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b04220ad..70dc9798 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,7 +126,7 @@ where - Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`. - Mark error enums as `#[non_exhaustive]`. -- Avoid `unwrap()` — use proper error propagation. When deliberately ignoring an error, use `.ok()` with a comment explaining why. +- Avoid `unwrap()` in non-test code — use proper error propagation. `unwrap()` is acceptable in tests and for provably infallible operations (with a comment explaining why). When deliberately ignoring an error, use `.ok()` with a comment explaining why. ```rust #[derive(Debug, Display, Error)] @@ -185,5 +185,5 @@ Before submitting, ensure: The CI script `test.sh` runs all of these across 5 feature combinations. You can run it locally with: ```sh -FMT=true LINT=true BUILD=true TEST=true ./test.sh +FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh ``` diff --git a/tests/sync_ai_instructions.rs b/tests/sync_ai_instructions.rs index 750d1252..f863fb10 100644 --- a/tests/sync_ai_instructions.rs +++ b/tests/sync_ai_instructions.rs @@ -1,7 +1,6 @@ //! The following tests check whether the AI instruction files are in sync. //! -//! All three files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) should have -//! identical content (except for the title line). +//! All three files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) should be identical. macro_rules! check { ($name:ident: $a_path:literal == $b_path:literal) => { @@ -9,10 +8,8 @@ macro_rules! check { fn $name() { let a = include_str!($a_path); let b = include_str!($b_path); - let a_body = strip_title(a); - let b_body = strip_title(b); assert!( - a_body == b_body, + a == b, concat!( "AI instruction files are out of sync: ", $a_path, @@ -24,10 +21,5 @@ macro_rules! check { }; } -/// Strip the first line (title) and return the rest. -fn strip_title(text: &str) -> &str { - text.split_once('\n').map_or("", |(_, rest)| rest) -} - check!(claude_md_vs_agents_md: "../CLAUDE.md" == "../AGENTS.md"); check!(claude_md_vs_copilot_instructions: "../CLAUDE.md" == "../.github/copilot-instructions.md"); From 7dcfdd6632eda37ba474e6bb039d8cb4445ed20d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 13:39:07 +0000 Subject: [PATCH 05/11] chore: include AI instruction files in package Ensures `include_str!` in the sync test compiles even from a packaged crate. https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- Cargo.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index 92b0ed2b..094ee4a6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -27,6 +27,9 @@ include = [ "/README.md", "/USAGE.md", "/LICENSE", + "/CLAUDE.md", + "/AGENTS.md", + "/.github/copilot-instructions.md", ] [lib] From a3bf1ea1842af0ab83909000ac1d224cd51d1a59 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 13:41:30 +0000 Subject: [PATCH 06/11] Revert "chore: include AI instruction files in package" This reverts commit 7dcfdd6632eda37ba474e6bb039d8cb4445ed20d. --- Cargo.toml | 3 --- 1 file changed, 3 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 094ee4a6..92b0ed2b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -27,9 +27,6 @@ include = [ "/README.md", "/USAGE.md", "/LICENSE", - "/CLAUDE.md", - "/AGENTS.md", - "/.github/copilot-instructions.md", ] [lib] From 11bbccc026a74bb878ec986ba6d0f7e93829ca9e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 13:50:48 +0000 Subject: [PATCH 07/11] docs: add explicit merged import style preference https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- CLAUDE.md | 2 +- CONTRIBUTING.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 059ce3ae..3d901475 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Commit format: Conventional Commits — `type(scope): lowercase description` - Version releases are the only exception: just the version number (e.g. `0.21.1`) -- Import order: internal (`crate::`/`super::`) → external crates → `std::` +- Import order: internal (`crate::`/`super::`) → external crates → `std::`, prefer merged imports - Use descriptive generic names (`Size`, `Report`), not single letters - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70dc9798..69c16c89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,8 @@ Automated tools enforce formatting (`cargo fmt`) and linting (`cargo clippy`). T ### Import Organization +Prefer **merged imports** — combine multiple items from the same crate or module into a single `use` statement with braces rather than separate `use` lines. + Imports are grouped in this order, separated by blank lines: 1. `use super::...` or `use crate::...` (internal) From 18a790261ad10cf0d8c774b3de18d0adf2d326df Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 14:04:20 +0000 Subject: [PATCH 08/11] docs: add setup prerequisites and Claude Code environment notes https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- CLAUDE.md | 2 ++ CONTRIBUTING.md | 9 +++++++++ 2 files changed, 11 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 3d901475..b535d091 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,4 +13,6 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - No `unwrap()` — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free +- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` +- If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69c16c89..9c026bac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -175,6 +175,15 @@ Use macros to reduce boilerplate for repetitive patterns (e.g. newtype wrappers, The crate uses `#![deny(warnings)]` — all warnings are treated as errors. Code must compile warning-free. +## Setup + +Install the required Rust toolchain and components before running any checks: + +```sh +rustup toolchain install "$(< rust-toolchain)" +rustup component add rustfmt clippy +``` + ## Automated Checks Before submitting, ensure: From f6b9f500feff8a58b6e2ad588204e3c1d0b163ac Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 14:07:41 +0000 Subject: [PATCH 09/11] docs: sync AI instruction files https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- .github/copilot-instructions.md | 4 +++- AGENTS.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 059ce3ae..b535d091 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,11 +6,13 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Commit format: Conventional Commits — `type(scope): lowercase description` - Version releases are the only exception: just the version number (e.g. `0.21.1`) -- Import order: internal (`crate::`/`super::`) → external crates → `std::` +- Import order: internal (`crate::`/`super::`) → external crates → `std::`, prefer merged imports - Use descriptive generic names (`Size`, `Report`), not single letters - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - No `unwrap()` — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free +- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` +- If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/AGENTS.md b/AGENTS.md index 059ce3ae..b535d091 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,11 +6,13 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Commit format: Conventional Commits — `type(scope): lowercase description` - Version releases are the only exception: just the version number (e.g. `0.21.1`) -- Import order: internal (`crate::`/`super::`) → external crates → `std::` +- Import order: internal (`crate::`/`super::`) → external crates → `std::`, prefer merged imports - Use descriptive generic names (`Size`, `Report`), not single letters - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - No `unwrap()` — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free +- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` +- If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes From 14aa601d12991f41e67b2cbbda72d1d7bf0a81b0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 14:14:02 +0000 Subject: [PATCH 10/11] docs: change "avoid unwrap()" to "minimize unwrap()" in non-test code https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- CLAUDE.md | 2 +- CONTRIBUTING.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b535d091..9e971138 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,7 +11,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` -- No `unwrap()` — use proper error handling +- Minimize `unwrap()` in non-test code — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it diff --git a/AGENTS.md b/AGENTS.md index b535d091..9e971138 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` -- No `unwrap()` — use proper error handling +- Minimize `unwrap()` in non-test code — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it diff --git a/CLAUDE.md b/CLAUDE.md index b535d091..9e971138 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` -- No `unwrap()` — use proper error handling +- Minimize `unwrap()` in non-test code — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c026bac..b733dbff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,7 +128,7 @@ where - Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`. - Mark error enums as `#[non_exhaustive]`. -- Avoid `unwrap()` in non-test code — use proper error propagation. `unwrap()` is acceptable in tests and for provably infallible operations (with a comment explaining why). When deliberately ignoring an error, use `.ok()` with a comment explaining why. +- Minimize `unwrap()` in non-test code — use proper error propagation. `unwrap()` is acceptable in tests and for provably infallible operations (with a comment explaining why). When deliberately ignoring an error, use `.ok()` with a comment explaining why. ```rust #[derive(Debug, Display, Error)] From e5f37bd2a27b2bd01b7172e68af11adcb7f1388e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Mar 2026 14:20:03 +0000 Subject: [PATCH 11/11] docs: add --toolchain flag to rustup component add command Without the flag, components install for the default toolchain rather than the one pinned in rust-toolchain. https://claude.ai/code/session_0118JGKVwhgbK8NwHfrorHfx --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- CLAUDE.md | 2 +- CONTRIBUTING.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9e971138..37c319de 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -13,6 +13,6 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - Minimize `unwrap()` in non-test code — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free -- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` +- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/AGENTS.md b/AGENTS.md index 9e971138..37c319de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,6 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - Minimize `unwrap()` in non-test code — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free -- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` +- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CLAUDE.md b/CLAUDE.md index 9e971138..37c319de 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,6 +13,6 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` - Minimize `unwrap()` in non-test code — use proper error handling - `#![deny(warnings)]` is active — code must be warning-free -- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add rustfmt clippy` +- Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b733dbff..c1c0d086 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -181,7 +181,7 @@ Install the required Rust toolchain and components before running any checks: ```sh rustup toolchain install "$(< rust-toolchain)" -rustup component add rustfmt clippy +rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy ``` ## Automated Checks