# Contributing
## Scope
`deep-delta-learning` is still an alpha research-oriented crate. Contributions should prioritize:
- Correctness over new surface area
- Typed errors over panics at user-facing boundaries
- Reproducible CLI and checkpoint behavior
- Tests that pin every bug fix
## Setup
```bash
git clone https://github.com/AbdelStark/ddl-rs.git
cd ddl-rs
cargo check
cargo test
cargo test --examples
cargo build --features tui
cargo clippy --all-targets --all-features -- -D warnings
```
For coverage locally, install `cargo-llvm-cov` and run:
```bash
cargo llvm-cov --workspace --all-features --lib --tests \
--ignore-filename-regex 'src/bin/' \
--summary-only
```
## Workflow
1. Start from a clean branch.
2. Make one coherent change at a time.
3. Add or update tests with every behavioral fix.
4. Update docs when the public contract changes.
5. Run the full validation set before opening a PR.
## Standards
- Keep tensor shapes explicit around rank-changing operations.
- Prefer typed errors at CLI, checkpoint, training, and evaluation boundaries.
- Do not silently coerce invalid input into placeholder metrics.
- Preserve the shipped CLI contract under `src/bin/ddl/`.
- Treat README/spec drift as a bug and fix it in the same change when allowed.
## Benchmarks
Hosted CI runners are too noisy for strict wall-clock budgets. The current CI policy enforces:
- deterministic benchmark regression logic in tests
- a CLI benchmark smoke run
- schema and gate compatibility for saved baselines
If you change benchmark report structure or gating semantics, update fixtures and tests together.
## Pull Requests
Include:
- the problem being fixed
- the user-visible behavior change
- commands you ran locally
- remaining risks, if any