Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (79 loc) · 7.6 KB

CONTRIBUTING.md

File metadata and controls

116 lines (79 loc) · 7.6 KB
Raw

Contributing to chio-developer-base

Thanks for your interest. This repo is public under Apache-2.0 and external contributions are welcome — but the project has strong opinions about what belongs in it. Read this before opening a PR.

What this project is

The dedicated knowledge base, vault, and developer-tooling stack for Chio — Backbay's capability-based agent runtime. The full design lives in PLAN.md; the charter in decisions/ADR-0000-charter.md. Read both first.

Before you contribute

There are five hard rules (lifted verbatim from AGENTS.md — they apply to humans and agents alike):

  1. Never write to Graphiti directly. The vault-sync daemon is the only writer to Graphiti. To add an episode, write vault/episodes/<id>.md.
  2. Never duplicate code into the vault. Source code lives in arc / platform / opus / etc. and is referenced by stable path + symbol.
  3. kb-engine/ cannot import chio_*. The boundary is enforced by CI (Phase 1+).
  4. Vault frontmatter is a contract. Every note has id, type, status. Bad frontmatter fails CI.
  5. The retrieval eval is the regression floor. Overall A required across the 9 categories from PR #599. If make kb-eval drops below A, revert; don't patch.

If your change conflicts with one of these rules, the rule wins. File an ADR if you genuinely think the rule is wrong — that's how it changes.

What to contribute

High-value contributions:

Lower-value contributions (please discuss before opening a PR):

  • New top-level vault folders. Requires an ADR per PLAN.md "Vault layout".
  • New Obsidian community plugins added to .obsidian/community-plugins.json. Plugin choices are an ADR-level decision.
  • Changes to the engine ↔ pack boundary. Always opens with an ADR.
  • Adjustments to outcome-eval targets in chio-pack/eval/outcomes.yml. These are decisions about what "the carve-out works" means and need an ADR.

How to contribute

Reporting issues

  • Search existing issues first.
  • For Phase 0 work, check the Phase 0 milestone — most outcome-eval work is already tracked there.
  • For new feature ideas, open a discussion-style issue (no template required) before writing code.

Pull requests

This repo enforces branch protection on main:

  • Direct pushes to main are blocked for non-admins.
  • PRs require 1 approving review before merging.
  • Force-pushes are blocked universally (including admins).

The flow:

  1. Fork the repo (external contributors) or create a branch (internal Backbay contributors with write access).
  2. Open an issue first for non-trivial changes. Briefly describe what you're proposing and why.
  3. Make your change on a feature branch. One coherent change per PR.
  4. Run make kb-eval-outcomes locally before pushing. The CI workflow (eval.yml) runs this on every PR; you'll get a comment with the eval-outcomes table.
  5. Open the PR with a description that:
    • Links the related issue.
    • States which (if any) ADR the change requires or modifies.
    • Reports the local make kb-eval-outcomes result.
  6. Address review feedback. Maintainers may ask for an ADR if the change touches load-bearing infrastructure — that's not pushback, it's the contract.

Local boundary check (make check-boundary)

The engine ↔ pack and pack ↔ pack boundaries (hard rule #3 above) are enforced in CI by ops/ci/check-imports.py. To catch a violation before pushing, run make check-boundary locally. The same check is collected by pytest (chio-pack/tests/test_check_imports.py::test_repo_clean) so it also fires on every uv run pytest invocation. To wire it as a git pre-commit hook (no .pre-commit-config.yaml is shipped — plugin choices are an ADR call), drop the following one-liner into .git/hooks/pre-commit and chmod +x it:

#!/bin/sh
exec make check-boundary

That's it. The hook is local-only (not versioned) and entirely opt-in.

The eval-gate contract

CI runs make kb-eval-outcomes on every PR. Once Phase 0 is complete (per ADR-0002 acceptance), the gate becomes blocking. Until then, it's informational — but PRs that visibly degrade an outcome eval will be asked to either revert or document the trade-off in an ADR.

The gate has an explicit escape hatch (Phase 2A+) for cases where a regression is intentional:

kb-gate: ack
> reason: revocation-window guard intentionally relaxed; ADR-NNNN

kb-gate: ack requires a reason. Reasons without a linking ADR are rejected.

Where to ask questions

Code style

  • Markdown: match the conventions in existing files. Frontmatter must validate against chio_pack/frontmatter.py (Phase 1+).
  • Python: target Python 3.11+. The two scripts under ops/scripts/ and the chio_pack/eval/runner.py skeleton are the style guides.
  • TypeScript (Obsidian plugins): match episode-promoter/src/main.ts.
  • Comments: lean toward "no comment" by default. Add a comment when the why is non-obvious — never to explain what well-named code already shows.

License and contributor sign-off

This project is licensed under Apache-2.0. By submitting a pull request, you agree your contribution is licensed under the same terms. We don't currently require a separate Contributor License Agreement (CLA) or DCO sign-off, but reserve the right to add one if the project grows.

See also