Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
68 lines (51 loc) · 2.29 KB

CONTRIBUTING.md

File metadata and controls

68 lines (51 loc) · 2.29 KB
Raw

Contributing

Thanks for improving Codex Usage Tracker.

Start with the contract

Read AGENTS.md and docs/INDEX.md. Work from one file under docs/roadmap/tasks/ and its controlling documents. Keep the branch and pull request focused on that packet, and update the checkbox ledger only after every acceptance criterion and required measurement passes.

For every upstream artifact consumed as truth, the packet must name and execute its producer-to-consumer seam check: exact producer identity, consumer path, independent truth source, and requalification set. Matching hashes or a prior packet's completion do not prove semantic compatibility. If a downstream consumer exposes a mismatch, stop it and add a corrective packet rather than silently changing expected output or historical evidence.

The replacement belongs under src/codex_usage_tracker/agent_kernel/. Do not import, migrate, or extend the frozen 0.28 spike under src/codex_usage_tracker/kernel/.

Local setup

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ".[dev]"

Checks

Run focused tests while implementing, then the smallest complete profile that covers the changed contract:

just vp  # fast maintained checks
just v   # complete local CI profile
just vc  # release/build candidate profile

At minimum, documentation-only changes must pass:

python scripts/check_release.py
git diff --check

Never bypass hooks. Include exact commands, measurements, deviations, and remaining risks in the pull request.

Test data

  • Use deterministic synthetic fixtures only.
  • Do not commit real Codex logs, prompts, responses, reasoning, commands, patches, tool-output bodies, credentials, private paths, or local databases.
  • Preserve missingness, provenance, and four-class token accounting in tests.
  • Do not add sanitization or redaction behavior to compensate for unsafe test data; replace the fixture with synthetic data.

Pull requests

Use a focused Conventional Commit and describe the user-visible contract, tests run, performance/storage/response measurements required by the packet, and rollback behavior. A meaningful stable diff receives at most one final read-only reviewer.