ADR 0008: Make Command Taxonomy and Workflow Entrypoints

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: A long Makefile lists many targets; without naming rules, every developer invents a personal script. That fragments onboarding (“how do I run what CI runs?”) and makes documentation brittle. Clear atomic commands (one job each) plus a few scenario entrypoints (fix → verify → release) match how people actually work.

We standardize on memorable verbs for whole workflows so new contributors do not hunt through the Makefile during every fix or release.

Decision

We use two levels of Make targets:

1. Atomic commands remain source-of-truth building blocks (format/lint/test/docs/etc.).
2. Scenario entrypoints provide memorable, high-level workflows.

Scenario entrypoints introduced:

• make fix - canonical fix workflow.
• make verify - canonical local quality gate.
• make release-check - canonical pre-release gate.
• make release DEPLOY_CMD='...' - canonical release execution flow.

Operational reference (diagrams and scenarios)

For grouped targets, PlantUML pipeline figures (sources under docs/uml/make/), and if → then onboarding flows, see the developer guide Make commands and workflows. It does not replace make help; it explains how composite targets relate for day-to-day use.

Command taxonomy

Atomic commands

• Environment: venv, install, requirements, env-check.
• Code quality: format-fix, format-check, lint-fix, lint-check, dead-code-check, type-check.
• Contracts: openapi-check, contract-test, openapi-accept-changes.
• Tests: test, test-one, test-warnings.
• Docs: docs-fix, docs-check.
• Local Docker stacks (optional): metrics — observability-up, observability-down, observability-smoke; structured logs — logging-up, logging-down, logging-reset, logging-smoke, logging-es-query (ADR 0023).
• Deploy primitive: external deployment command passed via DEPLOY_CMD.

Scenario entrypoints

• Fix loop: make fix.
• Local verification: make verify.
• Pre-push alignment with CI (dependency audit + strict docs sync): make verify-ci.
• Release gate: make release-check.
• Release execution: make release DEPLOY_CMD='...'.

Implementation rules

1. Keep one canonical command per workflow; avoid duplicate aliases with identical behavior.
2. When adding a new atomic target, update make help under Atomic commands.
3. When adding a new multi-step process, expose it as scenario entrypoint in make help.
4. Keep release flow explicit and parameterized via DEPLOY_CMD.

Consequences

Positive

• Lower onboarding and day-to-day cognitive load.
• Clear separation between reusable primitives and operational workflows.
• More consistent local and CI usage patterns.

Trade-offs

• Existing local habits may require migration to new canonical command names.
• Help text must stay curated when targets evolve.

Page history