diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e24c5900..aca62f32 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`) - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` +- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors - Minimize `unwrap()` in non-test code — use proper error handling - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags. diff --git a/AGENTS.md b/AGENTS.md index e24c5900..aca62f32 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`) - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` +- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors - Minimize `unwrap()` in non-test code — use proper error handling - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags. diff --git a/CLAUDE.md b/CLAUDE.md index 84945705..13c391ce 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`) - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` +- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors - Minimize `unwrap()` in non-test code — use proper error handling - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 444a1460..1a804e27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -198,7 +198,10 @@ where ### Error Handling -- Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`. +- Use `derive_more` for error types. Only derive the traits that are actually used: + - `Display`: derive when the type needs to be displayed (e.g., printed to stderr, used in format strings). + - `Error`: derive when the type is used as a `std::error::Error` (e.g., as the error type in `Result`, or as a source of another error). Not all types with `Display` need `Error`. + - A type that only needs formatting (not error handling) should derive `Display` without `Error`. - 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 diff --git a/template/ai-instructions/shared.md b/template/ai-instructions/shared.md index e24c5900..aca62f32 100644 --- a/template/ai-instructions/shared.md +++ b/template/ai-instructions/shared.md @@ -12,7 +12,7 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use `pipe-trait` for chaining through unary functions (constructors, `Some`, `Ok`, free functions, etc.), avoiding nested calls, and continuing method chains — but not for simple standalone calls (prefer `foo(value)` over `value.pipe(foo)`) - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` +- Error types: only derive `Display` and `Error` from `derive_more` when each is actually needed — not all displayable types are errors - Minimize `unwrap()` in non-test code — use proper error handling - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes. If a test fails with a hint about `RUSTFLAGS` and `--cfg pdu_test_skip_*`, follow the hint and rerun with the suggested flags.