# Project Agents — Policies and Best Practices
Purpose
- Define minimal, actionable rules for contributors to this Rust crate.
- Ensure code quality, stability, and predictable releases.
Scope
- Applies to all code under stac-client-rs, including tests and CI.
Rust best practices (concise)
- Prefer idiomatic Rust: ownership, borrowing, Result/Option, and explicit error types.
- Use expressive types and small, focused modules/functions.
- Format with rustfmt and enforce with CI: `cargo fmt -- --check`.
- Lint with clippy and treat warnings as errors in CI: `cargo clippy -- -D warnings`.
- Write documentation comments for public items; include examples where helpful.
- Use feature flags to guard optional functionality when appropriate.
Semantic versioning
- Follow SemVer (MAJOR.MINOR.PATCH).
- MAJOR: incompatible API changes.
- MINOR: additive, backwards-compatible functionality.
- PATCH: backwards-compatible bug fixes.
- Update Cargo.toml version and tag the commit (e.g., `v1.2.3`).
- Release flow: bump version → update changelog/notes → tag → publish.
Standard library preference
- Prefer Rust standard library and well-established crates from crates.io before adding new dependencies.
- Evaluate new dependencies by:
- Necessity: can std solve it?
- Maturity: downloads, recent activity, maintenance.
- Security and license compatibility.
- New dependency PRs must include a short rationale and alternatives considered.
Testing and full coverage requirement
- All public and critical internal code must be covered by tests.
- Unit tests, integration tests, and doctests are required where applicable.
- The project target is 100% line coverage (strict requirement).
- TEMPORARY EXCEPTION (Sept 2025): Minimum enforced in CI is currently 80% while backfilling tests for newly added functionality.
- TODO: Remove temporary 80% threshold and restore strict 100% gate once remaining test gaps (see issues tagged coverage-gap) are closed.
- Use a coverage tool (recommended: cargo-tarpaulin or grcov) in CI to measure coverage.
- PR must include coverage report or CI must assert the coverage threshold is met.
CI enforcement (example checks)
- On CI run:
- cargo fmt -- --check
- cargo clippy -- -D warnings
- cargo test --all --release
- Run coverage tool and assert 100% coverage
- Failing any check blocks merges.
Dependency additions
- When proposing a new dependency, include:
- Short justification and alternatives.
- Security/maintenance notes.
- Minimal reproducible example in the PR.
PR checklist (must be satisfied before merge)
- [ ] Code formatted: `cargo fmt`
- [ ] Linted: `cargo clippy` (no warnings)
- [ ] Tests included and passing: `cargo test`
- [ ] Coverage at 100% (or CI enforces)
- [ ] Version bumped when releasing, with a tag and changelog entry
- [ ] Dependency rationale included (if applicable)
- [ ] ADR/ASR review performed: relevant existing ADRs/ASRs referenced or updated
- [ ] New ADR/ASR drafted if change introduces a new architectural decision or capability gap
- [ ] ADR/ASR indexes updated (if new documents added)
Architecture governance (ADR / ASR)
- All architecturally significant changes (new features, cross-cutting concerns, dependency policy shifts, resilience strategies) must be mapped to an existing ASR or require drafting a new one under `docs/asr` before major implementation.
- If a solution path introduces a notable trade-off or rejects alternatives, an ADR (copy `0000-template.md`) must be created under `docs/adr` with next sequence number and linked in the ADR index.
- During PR review, maintainers verify:
- Each substantial change cites ADR IDs and/or ASR IDs in the PR description.
- No orphan architectural changes (code without governance docs).
- If contributor is unsure whether a change is architectural, they should open the PR with a draft checklist item requesting confirmation; reviewers will label accordingly.
- Minor refactors or pure test additions are exempt, but any change affecting public API, error semantics, feature flags, retry/auth/caching/pagination strategies, or performance characteristics is in scope.
- When a previous decision is reversed, the old ADR status becomes `Superseded` and a new ADR records updated reasoning.
- Gap analysis updates (ASR 0002) should be amended when a gap is closed or newly discovered.
- CI or review bots may in future enforce presence of ADR/ASR references; adopt practice now for consistency.
- Cross references MUST remain current: every ADR that fulfills or changes scope of an ASR must list the ASR IDs in a "Related ASRs" note (and vice versa the ASR index should reflect any ADRs that satisfy it). Update both sides whenever a status changes or a gap is closed.
- When closing a gap: (1) mark the gap row in ASR 0002 as addressed, (2) reference the implementing ADR, (3) if partial, note remaining sub-gaps.
- Reviewers should block merge if new capability code lacks corresponding ASR linkage or if existing references are stale.
Notes
- These rules are intentionally strict to ensure the client library remains safe, small, and maintainable.
- Exceptions require explicit approval from maintainers and should be documented in the PR.