Contributing

HFX is an open specification and toolkit repository. Contributions may target the specification, schemas, examples, conformance fixtures, validator, or future adapters.

Working Principles

Treat spec/HFX_SPEC.md as the canonical development spec.
Keep machine-readable contracts in schemas/.
Keep implementer-facing examples in examples/.
Keep validator fixtures in conformance/.
Keep Rust implementation code in crates/.

Spec Changes

If a change affects artifact shape, required fields, semantics, or validation behavior:

update the specification
update the relevant schema if one exists
add or adjust examples and conformance fixtures when applicable
record the rationale in docs/decisions/ for non-trivial design changes
add a short entry to the changelog

Validator Changes

Validator behavior should follow the spec and schemas. Avoid adding validator-only policy that is not grounded in the public contract.