docs/development/ holds one page per kind of change (settings, State Store and persistence, task lifecycle, workflows and steps, event automation, dashboard, agent execution and containers, processes and wiring, merging work), each naming every layer the change must reach and pointing at the document that owns the design. The docs build puts them in the development set; docs/index.md and CLAUDE.md link them. Also adds the container-profile case to the validator agreement test, the check the profiles work skipped.
43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
# Development guides
|
|
|
|
Checklists for changing Archie. Each page covers one kind of change and names
|
|
every place that change must reach, so a feature that works in one layer does
|
|
not silently stop at the next. The pages point at the documents that own the
|
|
design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than restating
|
|
them.
|
|
|
|
| Changing | Guide |
|
|
| --- | --- |
|
|
| A setting in `config.toml` or the dashboard | [Configuration settings](config-settings.md) |
|
|
| A stored field, table, RPC or error | [State Store and persistence](state-store-and-persistence.md) |
|
|
| Task statuses, fields or the task brief | [Task lifecycle](task-lifecycle.md) |
|
|
| Workflow definitions or step types | [Workflows and steps](workflows-and-steps.md) |
|
|
| Sources, event types, mappings or bindings | [Event automation](event-automation.md) |
|
|
| Anything under `ui/` | [Dashboard](dashboard.md) |
|
|
| The agent container, its image or its tools | [Agent execution and containers](agent-execution-and-containers.md) |
|
|
| A process, plugin engine, channel or NATS subject | [Processes and wiring](processes-and-wiring.md) |
|
|
| Merging a lane or a branch | [Merging work](merging-work.md) |
|
|
|
|
## Every change
|
|
|
|
- Write the failing test first for anything with logic, branching or a
|
|
contract, and check it fails on an assertion, not a compile error.
|
|
- Test through the path production uses. A test that sets a value directly on
|
|
the consumer proves nothing about the layers that normally deliver it.
|
|
- Run `task check` and let its exit status decide the commit:
|
|
`task check && git commit ...`. `task test` passes `-short`, which skips the
|
|
process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`
|
|
too when a change crosses a process or the database.
|
|
- Regenerate, never hand-edit, generated output: `task proto:generate`,
|
|
`go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,
|
|
`task ui`, `task docs:artifact`. `task proto:check` compares against the git
|
|
index, so stage regenerated contracts before running it.
|
|
- Stage by path, or read `git status` before `git add -A`. Tests that start
|
|
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
|
|
tree gets committed. `task check` also adds linter-tool lines to `go.sum`
|
|
(bead 1e37); restore `go.sum` before committing unless you changed a
|
|
dependency.
|
|
- A change to `docs/prds/` or `docs/architecture/` carries the regenerated
|
|
`docs/data/generated/dev-docs.json`, and PRD edits follow
|
|
`docs/prds/RULES.md` and pass `task docs:prds`.
|