Contributing

Axiolid values small, proven boundaries over broad claims. A change is not complete when it compiles; it is complete when its capability, dependency direction, and failure behavior are evident.

Before you file anything

Where things go decides the surface: new functionality and optimizations start as discussions, papercuts and bugs are issues, and every decision is recorded rather than silently dropped.

Local checks

cargo fmt --all -- --check
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
RUSTDOCFLAGS='-D warnings' cargo doc --workspace --no-deps
scripts/geometry-feature-matrix.sh
scripts/probe_layering_gate.sh

The feature matrix protects minimal builds. The probe mutates the declared layering boundary and proves the gate fails, then verifies byte-accurate restoration.

Design rules

• Keep Axiolid format-agnostic: source semantics belong in adapter projects.
• Do not add a concrete backend dependency to a representation or format boundary.
• Treat scalar paths as correctness oracles; benchmark and differentially test a faster path before claiming a performance win.
• Keep operation capability tied to an executable provider implementation.
• Record irreversible architecture choices under docs/adr/.
• Put open work in a GitHub issue, not in a checked-in plan. A code marker is written TODO(#N). A crate's README.md says what the crate is for and makes no coverage claim that the code and tests do not back (ADR 0078).

Documentation

The site is VitePress and deploys from main through GitHub Pages. Preview it locally:

npm --prefix docs ci
npm --prefix docs run docs:dev

Records

• CHANGELOG.md files follow Keep a Changelog.
• Write an ADR from docs/adr/_template.md before an irreversible boundary or dependency change.
• A research record in docs/research/ keeps measured evidence apart from proposals.
• cargo xtask docs generates every page derived from the crates: the crate reference (from each crate's manifest, README.md and CHANGELOG.md), the per-crate changelog, and docs/architecture/crate-map.md and dependency-graph.md. Do not edit them by hand; change the source and regenerate. cargo xtask docs --check runs in the gate and before every deploy. Package metadata does not prove a capability: the implementation and its conformance tests do.
• A published crate's README.md is its crates.io page. It ends with its docs.rs, reference-page and source links, and states no version or publication status; cargo xtask docs --check enforces both.

Diagrams, geometry, and equations

• Use fenced mermaid for architecture, state, and data-flow diagrams. Include accTitle and accDescr, and explain the same conclusion in nearby prose.
• Use fenced ASCII stl only for small, reviewable geometry examples. GitHub renders the source natively; the VitePress theme parses the same source locally with an event-driven viewer. Keep capability evidence in tests, not in the picture.
• Use $...$ and $$...$$ for equations, define every symbol, and state the assumptions under which the equation applies.
• Keep code, benchmark tables, file trees, and protocol records as code blocks; Mermaid is not a replacement for literal data.

See GitHub's primary documentation for Mermaid diagrams, STL models, and mathematical expressions.