Contributing¶
The canonical copy of this lives in
CONTRIBUTING.md
in the repo.
Setup¶
python -m venv .venv
.venv/bin/pip install -e '.[dev,docs]'
.venv/bin/pytest
.venv/bin/mkdocs serve # docs at http://127.0.0.1:8000
Ground rules¶
cryptographyis the only runtime dependency. A new runtime dependency needs an ADR and a strong reason.- No database adapters in this repo (ADR-0004). Store implementations live in downstream packages; here we maintain only the protocols and the conformance suite.
- Wire-format changes are breaking. If you change what
canonical_bytesproduces, what feeds anentry_hash, or anyto_dictshape, bump the relevantschemastring and update the golden vectors intests/test_canonical.pyon purpose. - Every store-protocol invariant needs a conformance test in
src/approvo/testing.py(approvo.testing). ruff check src/ tests/andpytestmust pass.mkdocs build --strictmust pass if you touched docs.
Architecture decisions¶
Non-trivial design changes get an ADR in docs/adr/,
numbered, following the Context / Decision / Consequences format. ADRs are
immutable once accepted — supersede rather than edit.
Pull requests¶
- One logical change per PR.
- Reference the ADR or issue in the description.
- CI runs the test suite on Python 3.11–3.13,
ruff, and a strict docs build.
Reporting security issues¶
Open a GitHub security advisory, or email the address in
pyproject.toml. Don't file public issues for suspected vulnerabilities.
See Security model.