TacidOS
DevelopersGitHub

How to help

Contributing

How to help build the nervous system.

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/boards/, crates/tacid-tools/embedded): probe and target descriptions for embedded workflows.
  • 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: nix flake check, cargo fmt --check, cargo clippy, cargo test, and the VM test for any module you touched.
  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.