---
## Contributing to eeco
eeco is a solo project with a deliberately small contribution surface. This is a
lightweight contract — how to build, which checks must pass, and the rules a
change holds to — not community-health boilerplate. For how to *add* something —
a workflow, a config key, a verb — see [EXTENDING.md](EXTENDING.md).
## Build and checks
eeco builds with the Go toolchain through a `Makefile`:
| Command | What it does |
| -------------------- | ---------------------------------------------------------------------------- |
| `make build` | Build the single `eeco` binary. |
| `make verify` | `go build ./...` + `go vet ./...` + `go test ./...`. |
| `make gates` | Run the `comment-hygiene`, `leak-guard`, and `version-sync` workflows. |
| `make lint` | `golangci-lint` — must report **0 issues**. |
| `make cover-check` | Fail if total statement coverage drops below the ratchet floor. |
| `make bench` | Scanner benchmarks; keep them under the five-second budget. |
| `make sync-guide` | Mirror `docs/USAGE.md` into the in-binary guide after editing it. |
## Definition of Done
A change is done when **all** of these hold:
- **`make verify` green** — build, vet, and tests pass.
- **`make gates` green** — `comment-hygiene`, `leak-guard`, `version-sync`.
- **`make lint` green** — `golangci-lint`, 0 issues.
- **`make cover-check` green** — total statement coverage does not regress.
- **Additive over the public surface** — no change to an item frozen in
[`docs/PUBLIC_API.md`](docs/PUBLIC_API.md) unless a semver bump is explicitly
declared; when one is, the README version badge is bumped **before** the tag.
- **No AI attribution** — no AI-tool fingerprint or `Co-Authored-By` trailer in
any commit, tag, file, or PR body.
- **CHANGELOG entry when user-facing** — a binary- or user-facing change gets a
[CHANGELOG.md](CHANGELOG.md) entry; infra-only changes (CI, scripts) do not.
## Public surface and versioning
From v0.1.0, eeco follows Semantic Versioning over the surface frozen in
[`docs/PUBLIC_API.md`](docs/PUBLIC_API.md): the CLI verbs and flags, the
`eeco go --json` keys, exit codes, config keys, memory frontmatter fields, the
queue / ledger / hook formats, and the builtin workflow names. Nothing outside
that list is covered. Adding to the surface is a MINOR bump; post-1.0, changing
or removing a frozen item is a MAJOR bump with the deprecation window described
in [`VERSIONING.md`](VERSIONING.md). While eeco is pre-1.0 (`v0.x`) a MINOR MAY
change or remove a frozen item with a CHANGELOG migration note — see
[`VERSIONING.md`](VERSIONING.md) §2.1. Keep changes additive by default.
## Trust boundaries
Three invariants are sacred and are pinned by the boundary suite
(`*_boundary_test.go`):
- **The engine never writes the tracked tree.** Only the command-layer
`initgit.go` / `historygit.go` write git, and only to the workspace's own
private history — never the host repository.
- **Hooks stay reversible.** Every hook records its install in a ledger and
removes byte-identically; disabling a hook restores the prior state exactly.
- **AI stays gated.** No AI call happens without consent and budget, and when
memory or input is malformed the AI path degrades instead of failing the
command.
A change that touches these areas keeps the boundary suite green. Treat a
boundary-test failure as a design error, not a test to update.
## Working habit
Big or design-forked changes get a short planning pass before code; small,
mechanical changes can be planned and built in one go. Either way: edit on a
branch, get the Definition of Done green, keep the change additive (or declare
the bump), add a one-line CHANGELOG entry when it is user-facing, and open a PR.
## Pull requests
Clone, branch, and make your change. Run `make verify`, `make gates`,
`make lint`, and `make cover-check` until they are green; intent-add any new
files (`git add -N `) before `leak-guard` so it scans them. Open the PR
with the [template](.github/PULL_REQUEST_TEMPLATE.md) and link any
[issue](.github/ISSUE_TEMPLATE).
---
[← Prev: Extending](EXTENDING.md) · [Next: Upgrading →](docs/UPGRADING.md)
