1  # Contributing
 2  
 3  ## Getting Started
 4  
 5  ```bash
 6  # Build
 7  cargo build
 8  
 9  # Run all tests
10  cargo nextest run --workspace
11  
12  # Run doc tests
13  cargo test --all --doc
14  
15  # Lint
16  cargo fmt --all --check
17  cargo clippy --all-targets -- -D warnings
18  
19  # Security audit
20  cargo audit
21  
22  # License and ban check
23  cargo deny check
24  ```
25  
26  ## Documentation Standards
27  
28  Every public function, struct, trait, and enum **must** have a rustdoc comment. Follow the format from `CLAUDE.md`:
29  
30  ```rust
31  /// Short description.
32  ///
33  /// Args:
34  /// * `param_name`: What this parameter represents and its constraints.
35  ///
36  /// Usage:
37  /// ```ignore
38  /// let result = my_function("example", 42)?;
39  /// ```
40  pub fn my_function(param_name: &str, count: usize) -> Result<Output, MyError> {
41      // implementation
42  }
43  ```
44  
45  Rules:
46  - Private functions do not require doc comments unless the logic is non-obvious.
47  - Do not add comments that explain *what* the code does — name the function and its parts clearly instead.
48  - Do add comments that explain *why* a particular decision was made (opinionated choices, non-obvious tradeoffs).
49  - Broken intra-doc links are a compile error (`#![deny(rustdoc::broken_intra_doc_links)]`).
50  
51  ## Code Style
52  
53  - No `println!` or `eprintln!` in library crates (`#![deny(clippy::print_stdout, clippy::print_stderr)]`).
54  - No `Utc::now()` or `SystemTime::now()` in domain logic — inject `ClockProvider` (see ARCHITECTURE.md).
55  - No `std::env::var()` in domain logic — use `EnvironmentConfig` abstraction.
56  - Domain errors use `thiserror` enums. `anyhow` is only for CLI and server crates.
57  - All new port traits live in `src/ports/` with a fake in `auths-test-utils/src/fakes/` and a mock in `auths-test-utils/src/mocks/`.
58  
59  ## SemVer Policy
60  
61  See `RELEASES.md`. For changes to `auths-verifier`, `auths-core`, or `auths-sdk`:
62  
63  - **Additive changes** (new public items, new optional fields): minor version bump.
64  - **Breaking changes** (removed/renamed items, changed signatures): major version bump (or `0.(x+1).0` while in pre-release).
65  - CI enforces this via `cargo-semver-checks` on all pull requests.
66  
67  ## Testing
68  
69  Follow the test pyramid (see ARCHITECTURE.md):
70  
71  1. **Unit tests** — use `auths-test-utils::mocks` (mockall). No I/O.
72  2. **Integration boundary tests** — use `auths-test-utils::fakes` + contract macros. No disk or network.
73  3. **E2E tests** — use `auths-test-utils::git::init_test_repo()` for real Git I/O.
74  
75  All unit tests must pass with network blocked (`cargo test --lib --workspace` behind iptables in CI).
76  
77  ## Pull Request Checklist
78  
79  - [ ] `cargo fmt --all` passes
80  - [ ] `cargo clippy --all-targets -- -D warnings` clean
81  - [ ] `cargo nextest run --workspace` green
82  - [ ] `cargo test --all --doc` green
83  - [ ] Public API changes documented with `Args:` and `Usage:` blocks
84  - [ ] New port traits have a fake and/or mock in `auths-test-utils`
85  - [ ] Breaking changes bumped version per `RELEASES.md`