donglora/vendor/zerocopy/agent_docs/validation.md

Validating Changes

This document covers the procedures and requirements for validating changes to the project, including linting, testing, and pre-submission checks.

Linting

Clippy should always be run on the nightly toolchain.

./cargo.sh +nightly clippy
./cargo.sh +nightly clippy --tests

Strict Linting

• We deny warnings in CI. Even warnings not explicitly listed in lib.rs will cause CI to fail.
  • Why: We maintain a zero-warning policy so that new warnings (which often indicate bugs) are immediately obvious and not obscured by existing ones.
• Do not introduce new warnings.
• Respect the strict deny list in src/lib.rs.

Validating Changes

Ensure the library builds on all supported toolchains and that Clippy passes.

./cargo.sh +msrv check --tests --features __internal_use_only_features_that_work_on_stable
./cargo.sh +stable check --tests --features __internal_use_only_features_that_work_on_stable
./cargo.sh +nightly check --tests --all-features
./cargo.sh +nightly clippy --tests --all-features --workspace

Note: Tests are rarely toolchain-sensitive. Running tests on nightly is usually sufficient.

Testing Strategy

• Unit Tests: Place unit tests in a mod tests module within the source file they test.
• UI/Compile-Fail Tests:
  • zerocopy: Place in tests/ui-* (top-level). The top-level tests directory contains only UI tests.
  • zerocopy-derive: Place in zerocopy-derive/tests/ui-*.
• Derive Integration Tests: Place integration tests for derive macros in zerocopy-derive/tests.
• Derive Output Tests: Place unit tests that verify the generated code (token streams) in zerocopy-derive/src/output_tests.rs.
• Formal Verification (Kani): Place Kani proofs in a mod proofs module within the source file they test.
  • Purpose: Use the Kani Rust Verifier to prove the soundness of unsafe code or code relied upon by unsafe blocks. Unlike testing, which checks specific inputs, Kani proves properties for all possible inputs.
  • How to Write Proofs:
    • Harnesses: Mark proof functions with #[kani::proof].
    • Inputs: Use kani::any() to generate arbitrary inputs.
    • Assumptions: Use kani::assume(condition) to constrain inputs to valid states (e.g., align.is_power_of_two()).
    • Assertions: Use assert!(condition) to verify the properties you want to prove.
  • CI: Kani runs in CI using the model-checking/kani-github-action with specific feature flags to ensure compatibility.

Feature Gates

When editing code gated by a feature, compile with and without that feature.

./cargo.sh +stable check --tests
./cargo.sh +stable check --tests --feature foo