Skip to content

Contributing

Thanks for considering it. TOVIO ships under a per-component ("open-core") licensing model: the core engine, the CLI, and the SDKs are Apache-2.0 (OSI open source); the Forge and the enterprise modules are commercial. Elastic-2.0 was retired from this project ([ADR-0312]). This page is the friendly overview; the binding documents are LICENSE, LICENSE-APACHE, docs/cla/CLA.md, CONTRIBUTING.md, GOVERNANCE.md, and SECURITY.md in the project repository. For a fuller breakdown see the FAQ license entry. Every project space, the public feedback portal included, is governed by the code of conduct.

The shape of the project

TOVIO is a Rust workspace with a deliberate boundary. The engine and its thin I/O wrappers are Rust; TypeScript lives only at the edges.

  • tovio-core --- the engine: object store, change model, BLAKE3 addressing, chunking, crypto, conflict and CRDT merge. It does no I/O --- no filesystem, no network, no clock, no config. Every such input is injected by the caller, which is what keeps the engine deterministic and testable.
  • tovio-cli, tovio-forge, tovio-keystore --- the thin wrappers (terminal, network/storage, OS keychain) over the engine.
  • tovio-proto --- the wire types and codecs shared by the CLI and the Forge.
  • tovio-node-bindings --- the NAPI bridge that exposes the engine to JavaScript/TypeScript.
  • packages/* --- the TypeScript edges (MCP server, VS Code extension, web UI, SDK). They call the engine only through the bindings; they never reimplement engine logic.

The core/edge split is an architectural boundary, not a style preference. A pull request that adds I/O to tovio-core is wrong by construction --- push the I/O up into a wrapper instead.

From idea to merged change

The path is short: read the docs map → make a focused change → pass the gates locally → sign the CLA and sign off your commits → open a pull request citing the requirements and decisions it touches → maintainer review and green CI → merged. In a little more detail:

  1. Keep it focused. One logical change per pull request. A tight diff is easier to review and easier to revert.
  2. Pass the gates locally (next section) before you push --- they're the same ones CI runs.
  3. Sign the CLA and sign off your commits (below).
  4. Open the pull request with a clear description of what it changes and why.
  5. Get a review. Every pull request needs at least one maintainer review and green CI. Changes that touch crypto, the storage format, enforcement, or the audit chain get extra scrutiny.

The gates your change must pass

These are the same checks CI runs. Clear them locally first:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo nextest run --workspace
cargo test -p tovio-core --test conformance                             # the versioned corpus
pnpm -r lint && pnpm -r test                                            # if you touched the TS edges

On top of those, CI enforces a determinism gate, the crypto test suite, a fuzz-corpus smoke replay, and three lints: no secrets in objects/, error-catalog completeness, and requirement coverage.

P0 failures block merge, unconditionally

Data integrity, determinism, crypto safety, and no-data-loss are P0 properties. A failure in any of them blocks merge with no exceptions. And if you're fixing a P0 bug, the regression test that fails without your fix must land before the fix --- linked to the requirement it covers.

Conventions a reviewer will hold you to

  • tovio-core stays I/O-free. No filesystem, network, environment, terminal, or ambient clock --- inject everything.
  • Format and lint are gates, not suggestions. cargo fmt and cargo clippy -D warnings both block CI.
  • Every new user-visible error gets a catalog entry. Errors carry a stable TVO-AREA-NNN code and render in three parts --- what happened, why, what to do next. A CI lint fails the build on any constructed error without a catalog entry.
  • Secrets are zeroized and never leak. Key material is wrapped in a zeroizing type and must never reach objects/, the wire, logs, or the op-log. A lint enforces it.

Sign the CLA, then sign off every commit

TOVIO uses a Contributor License Agreement, not a bare DCO. Per-component licensing is why: the project ships a commercial Forge alongside the Apache-2.0 engine, which requires TOVIO to hold the rights to sublicense and relicense contributions. The CLA does not take your rights away --- you keep the copyright in your contribution.

First-time contributors sign once, and the ceremony is in-repo (no third-party service): add yourself to the versioned roster docs/cla/signatures.json in the same pull request as your first contribution, quoting the acceptance sentence from docs/cla/CLA.md §5 in that commit's message. A merge-blocking CI gate fails any pull request containing a commit whose author is not on the roster, and validates the roster itself on every run. Specification and conformance-corpus contributions are covered by the same CLA; for employer-owned work, contact the maintainers about a corporate CLA before submitting.

On top of the CLA, sign off every commit with a real name and email matching your author identity:

git commit -s -m "Add chunk-manifest dedup property test"

That appends a Signed-off-by: line. If you forget, git commit --amend -s (or git rebase --signoff) fixes it.

The CLI stays small --- on purpose

Git ships around 137 top-level commands; TOVIO deliberately won't repeat that. The rule is simple:

If you add a top-level command, you must remove or merge one --- and every command must pass the "do developers actually ask for this?" test before it ships.

New functionality should usually become a subcommand, a flag, or an entry in a progressive-disclosure tier --- not another top-level verb. Destructive commands require an explicit, spelled-out confirmation, never a bare --yes. Adding or removing a top-level command is a significant decision; expect to justify it.

How decisions get made

TOVIO is currently a BDFL project --- a single project lead holds final say while the architecture is being laid down. "Benevolent" is load-bearing: decisions are made by consensus where it exists.

This model is a starting point, not the destination. As the contributor base grows, governance broadens along a deliberate, publicly-announced path: trusted contributors become maintainers over specific areas, then a steering group takes on cross-cutting decisions, and --- if adoption warrants --- governance may move to a neutral foundation.

Reporting bugs vs. reporting vulnerabilities

This distinction matters more here than in most projects, because the permission system is security-critical.

  • A normal bug, feature, or question → post it on the feedback portal at https://tovio.dev/feedback (see feedback, roadmap and updates).
  • Anything that could expose protected content, leak a secret, forge a signature, or bypass an enforcement stage → a vulnerability. Do not open a public issue. Follow the coordinated- disclosure process in SECURITY.md. The crypto and permission system is the highest-severity surface in the project --- please treat it accordingly.

Data boundaries while contributing

The current CLI has no product-analytics uploader. That does not make every contribution workflow local: the Git host, CI provider, package registries, issue tracker, and any Forge or remote you explicitly invoke receive the data required by those operations under their own configuration and policies. Keep protected content, keys, credentials, customer data, and private-repository details out of public issues, test fixtures, logs, and build artifacts. Follow SECURITY.md for a vulnerability or potential disclosure.

Welcome aboard --- and thank you for helping build trustworthy developer infrastructure.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure