Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
153 lines (99 loc) · 8.85 KB

CONTRIBUTING.md

File metadata and controls

153 lines (99 loc) · 8.85 KB
Raw

Contributing to code-oz

Thanks for your interest in code-oz. This guide covers the setup, the test discipline, the commit and PR conventions, and the cross-model review rule that every substantive change passes through.

code-oz is a public alpha. Contributions that sharpen the truth, fix bugs, add deterministic tests, harden the install channels, or improve docs are very welcome. Contributions that add new gate authority, new providers, or new milestones need to land via the milestone process described in docs/design/ROADMAP.md and the CLAUDE.md non-negotiables — open a discussion first.

Local setup

git clone https://github.com/omerakben/code-oz.git
cd code-oz
bun install
bun run typecheck
bun test ./tests

Requirements:

  • Bun 1.3.0 or newer (bun --version). The repo's lock file is Bun's; npm and pnpm are not supported for local development.
  • Node 18 or newer for the npm wrapper smoke (node --version).
  • macOS arm64, macOS x64, Linux x64, or Linux arm64. Windows local development is not currently supported (the npm wrapper and binaries are Unix-only).

The root CI command is bun test ./tests. The broader local command bun test also picks up tests under code-oz-gui/ when that sub-project's dependencies are installed. Exact test counts drift as suites are added; current receipts live in docs/RECEIPTS.md.

Test discipline

Offline by default

Every test in tests/ runs offline against FakeProvider. No live LLM call, no network egress, no provider credentials. CI does not have provider credentials and must stay green.

bun test ./tests       # root CI suite
bun test               # broader local suite, including code-oz-gui tests when its deps are installed
bun test --watch       # iterative loop
bun test path/to/file  # one file

If you are touching the GUI, install and test the sub-project separately:

cd code-oz-gui
bun install
bun run typecheck
bun test tests/unit

Opt-in live-provider tests

A small number of tests exercise a real live provider (today only xAI). They are gated behind two env vars and skipped by default:

export CODE_OZ_LIVE_PROVIDER_TESTS=xai
export CODE_OZ_LIVE_XAI_MODEL=grok-2-1212  # or another supported variant
export XAI_API_KEY=...                      # your xAI key
bun test tests/providers-xai-live.test.ts

Live-provider tests must:

  • Remain opt-in (skipped when env flags are missing).
  • Cost less than $0.50 per full run.
  • Be deterministic against the live provider's documented response contract; if the provider drifts, the test reports the drift, not a flaky failure.

RED-first for behavior changes

Any change that alters runtime behavior (a new gate, a new provider error code, a new artifact field, a new CLI flag that changes a decision) follows rule 22 from CLAUDE.md: write the failing test first, run it to confirm it fails for the right reason, then write the minimal implementation, then run the test again to confirm it passes. The detailed sequence lives in src/agents/defaults/builder.md.

Pure documentation changes, dependency bumps that pass existing tests, and refactors that preserve external behavior are exempt from RED-first.

Commit conventions

We use Conventional Commits:

type(scope): one-line subject

Optional body explaining what changed and why.
References to design docs or Codex review threads in the body.

Common types: feat, fix, refactor, test, docs, chore, perf.

Common scopes: readme, providers, gates, cli, demo, package, the milestone identifier (m17, w3a), or a directory.

What NOT to put in commits

  • No emojis in commit messages, code, or PR descriptions.
  • No Co-Authored-By: Claude footers unless the contributor explicitly requested them.
  • No squash-commit messages with raw model output. Edit the message before committing.
  • No secret material (API keys, tokens, customer data, internal hostnames) anywhere in the diff or message.

Branching and merge workflow

The repo is trunk-based (locked 2026-05-29). main is the protected trunk; everything else is a short-lived branch.

  • Branch from the latest main: git fetch origin && git switch -c feat/<slug> origin/main. Never branch from another topic branch.
  • Prefixes: feat/, fix/, refactor/, test/, docs/, chore/. After the slash, a short kebab-case slug, optionally issue-scoped: fix/123-worktree-reset-on-restart.
  • One branch = one PR = one concern. If a branch grows a second concern, cut a second branch.
  • Open the PR the same session and keep branches short-lived. On merge the branch auto-deletes — do not delete it by hand.
  • Never push worktree-* scratch branches; git worktrees stay local.

Merging. PRs squash-merge into main (merge commits and rebase-merge are disabled), so one PR becomes exactly one conventional commit on main. The PR title is the squash commit subject, so it must be Conventional-Commit form.

main is protected. Required status checks (bun test on ubuntu-latest, bun test on macos-latest), strict/up-to-date, linear history, no force-push, no deletion, PR-before-merge — enforced for everyone including admins. There are no direct pushes to main.

Releases. Annotated SemVer tags (vX.Y.Z-alpha.N) on a green main commit, cut behind a chore/release-* PR (version bump + CHANGELOG) so the bump itself passes CI. One tag per release; tags are never moved.

Pull request expectations

The basics

  • One coherent change per PR. If the PR description grows past three bullet points, consider splitting.
  • Tests pass locally (bun test ./tests from the repo root; add bun test or GUI commands when the change touches those surfaces) before opening the PR.
  • The PR template (.github/pull_request_template.md) walks you through the checklist: summary, files changed, testing, breaking-change flag.
  • Link any relevant design doc, GitHub issue, or Codex review thread in the description.

Cross-model peer review (substantive changes only)

The project enforces a cross-model peer review discipline for changes that touch the orchestrator spine, the provider contract, the gate machinery, the CLI surface, or the release workflow. The discipline is named in CLAUDE.md:

  1. Planning convergence: write a docs/design/CODEX_BRIEFING_<topic>.md, dispatch it to Codex with model: gpt-5.5 and sandbox: read-only, capture the response, and synthesize before any code lands.
  2. Implementation completion: dispatch Codex again on the implementation commit. Codex returns one of push / fix-first / debate-required. Block-push findings close in a follow-up commit before the PR merges.

Pure documentation changes, typo fixes, and dependency bumps that pass existing tests do not require the Codex review pass.

If you are unsure whether your change is "substantive": open a draft PR and ask. The maintainers will tag it cross-review-needed or cross-review-skip.

Provider test policy

When adding a new provider adapter or modifying an existing one:

  1. Stub coverage first. Add a unit test that exercises the adapter through FakeProvider (or with the adapter's HTTP path mocked at the fetch boundary). This keeps CI offline.
  2. Live-provider test gated by env vars. Add a separate file under tests/providers-<name>-live.test.ts that runs only when CODE_OZ_LIVE_PROVIDER_TESTS includes the provider id. Document the env-var contract at the top of the file.
  3. Redaction test required. Every HTTP adapter must include a test that verifies API keys never appear in serialized events.jsonl, error messages, or NEEDS_INTERVENTION.json payloads. Pattern at tests/providers-xai-redaction.test.ts.

What to expect after opening a PR

  • A maintainer triages within a few days. Triage adds labels and may ask for clarification.
  • Substantive PRs get a Codex review pass (see above). The review verdict is recorded in the PR conversation.
  • Block-push findings close in a follow-up commit on the PR branch before merge.
  • The merge strategy is squash-merge into main; the head branch auto-deletes on merge. Release tags are cut on main behind a chore/release-* PR (see "Branching and merge workflow").

Code of conduct

Participation in this project is governed by CODE_OF_CONDUCT.md. Be excellent to one another.

Questions

Open a discussion at github.com/omerakben/code-oz/discussions for design questions, "is this the right approach" questions, and roadmap discussions.

Open an issue at github.com/omerakben/code-oz/issues for confirmed bugs, install problems, demo failures, and concrete feature requests. The four issue templates will guide you.

For security issues, see SECURITY.md.