Contributing

One-time setup

git clone https://github.com/alliecatowo/puml
cd puml
./scripts/setup.sh

Fast local loop

./scripts/dev.sh        # fmt + clippy + test

Quality gate

./scripts/check-all.sh           # full: fmt + clippy + test + coverage + release build + bench gates
./scripts/check-all.sh --quick   # skip coverage and release build; keep quick bench gates

CI runs the quick gate on PRs and the full gate on main. The contracts:

.github/workflows/pr-gate.yml → fmt + clippy + test + coverage gate + quick check-all.
.github/workflows/main-gate.yml → full check-all + bench evidence artifacts.

Tests

The test corpus lives in tests/ with snapshots under tests/snapshots/. The big ones to know:

integration.rs — broad smoke and parity tests.
render_e2e.rs — end-to-end render asserts.
docs_harness_contract_audit.rs — docs-as-tests harness.
parity_*_audit.rs — cross-dialect parity sweeps.
coverage_*.rs — coverage gate enforcement.

cargo test
cargo test -- --nocapture render_e2e

Docs-as-tests

Every example in docs/examples/ is both:

Linked from the gallery on this site.
Asserted by the docs render check (scripts/render_check.py).

When you commit a new .puml, commit the matching .svg artifact alongside it. The site’s scripts/build-site.mjs walks the corpus on build, so new examples surface automatically on the next deploy.

Branch protection

The branch-protection contract is documented in docs/internal/branch-protection.md and validated by:

./scripts/branch-protection.sh verify

Benchmarks

./scripts/bench.sh                  # full benchmark refresh
./scripts/bench.sh --quick          # quick profile
./scripts/bench.sh --enforce-gates  # perf + binary-size gates

Style

Rust 2021 edition.
cargo fmt and cargo clippy -- -D warnings are non-negotiable.
No new production deps without a written justification.
No unwrap / expect in library code outside of test fixtures.
No unsafe outside of carefully scoped, audited FFI boundaries.

Where to ask questions

Start a discussion at https://github.com/alliecatowo/puml/discussions for usage questions, early ideas, showcases, parity reports that need shaping, and AI-swarm workflow notes.
Open an issue at https://github.com/alliecatowo/puml/issues when there is a reproducible bug, scoped compatibility gap, docs task, tooling task, or regression.
Tag issues with the relevant family or area (area/sequence, area/cli, area/wasm).

The full issue-vs-discussion routing guide lives in the repository at docs/discussions.md.