Contributing

Thank you. Read MANIFESTO.md first, then skim docs/decisions/ so you know which questions are already settled. PLAN.md says which phase we are in and what is wanted next.

Easy on-ramps

• Hardware modules (nix/hardware/): a quirk module for a machine you own, with the facts tacid doctor should check.
• Models registry (models/registry.toml): an entry for a model with a clear license, hashes, sizes, backends and intended tasks.
• Design tokens and themes (design/): palette and typography work that stays inside the design system.
• Doctor checks (crates/tacid-doctor): a deterministic check for a domain that currently needs a wiki.
• Board definitions (nix/hardware/): probe and target descriptions for embedded workflows. The probes a machine knows are curated udev profiles; crates/tacid-facts reads what is on the bus and says what each thing is for.
• Documentation: anything in docs/ that is wrong, unclear or missing.

Workflow

1. Open or find an issue. Large changes need an RFC first (see GOVERNANCE.md).

2. Branch from main. Keep the change focused; do not widen it.

3. Every commit is signed off (git commit -s, Developer Certificate of Origin).

4. Run the fast checks before pushing: cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace --all-targets, and — for anything that touches the module layer — nix build .#checks.x86_64-linux.face and .#checks.x86_64-linux.session, which are seconds rather than an hour.

   Not nix flake check. It builds the four checks that boot machines, and on a runner or a laptop with no KVM device QEMU emulates one instruction at a time: the installation test alone is the better part of an hour. Continuous integration does not run it either, and says why in .github/workflows/ci.yml. Run the VM test for the module you touched by name — nix build .#checks.x86_64-linux.lifecycle and its three siblings — and expect to wait.

5. Open a pull request. Continuous integration must be green. An area reviewer will look at it; changes to the signed core need two approvals including the maintainer’s.

Standards

• Rust: rustfmt and clippy clean; no unsafe without a comment that justifies it; no unwrap/expect in daemons; errors are typed; every public item is documented; every crate has tests. One workspace, shared types, no duplicated protocol definitions.
• Nix: nixfmt; every tacid.* option has a description, an example, and validation that fails at evaluation with a message an agent can act on; every tacid.services.* option declares its persistent state; every module has a VM test.
• Documentation: one idea per sentence; say what and why; no marketing.
• Design: everything visual is generated from the design tokens. No hard-coded colours.

Generated code

If a change is substantially produced by an AI system (including a Tacid machine’s own proposals), say so in the pull request. You sign it, you are responsible for it, and you have read it.

Security

Never file a vulnerability as a public issue. See SECURITY.md.

Changing a decision

Decisions live in ADRs. To change one, write a superseding ADR that says what changed and why, and open it as a pull request. Arguments belong in the ADR, not in a chat log.