Skip to content

Spec Development Workflow

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Development Workflow

Part of the Technical Specification. Requirement prefix: DEV. Makes Development Process and Contributing normative.

1. Branching

Trunk-based development with short-lived branches.

gitGraph
  commit id: "main"
  branch feat-charging-options
  checkout feat-charging-options
  commit id: "feat: charging options"
  commit id: "test: parity fixtures"
  checkout main
  merge feat-charging-options id: "squash merge"
  branch fix-cursor-expiry
  checkout fix-cursor-expiry
  commit id: "fix: cursor expiry"
  checkout main
  merge fix-cursor-expiry id: "squash merge 2"
  commit id: "chore: release 1.1.0" tag: "v1.1.0"
Loading
ID Requirement Verification
DEV-001 main MUST always be releasable. Work happens on branches named <type>/<issue>-<slug> that live at most a few days; long work is split or hidden behind a feature flag (REL-010). Review
DEV-002 Every change MUST arrive by pull request; direct pushes to main are blocked. Ops
DEV-003 Pull requests MUST be squash-merged with a title in Conventional Commits 1.0.0 form (feat:, fix:, perf:, refactor:, docs:, test:, build:, ci:, chore:, with ! or a BREAKING CHANGE: footer for a breaking change). Lint
DEV-004 A pull request SHOULD stay under 400 changed lines excluding generated files and fixtures; larger ones MUST explain why. Review

2. Review

ID Requirement Verification
DEV-010 Every pull request MUST have at least one approving review from a code owner who is not the author; stale approvals are dismissed by new commits. Ops
DEV-011 Reviewers MUST check: correctness against the cited requirement ids, tests at the right layer, licence and attribution impact, no collection vocabulary or internal names, configuration instead of literals, documentation and changelog. Review
DEV-012 Security-relevant changes need a second review (SSC-018). Changes to this specification need the owner's approval. Review
DEV-013 Review comments MUST be resolved before merge; disagreements are settled by the owner, with an ADR when the decision is significant. Ops

3. Required checks

Formatting, lint, scope lint, configuration lint, type checks (where the language has them), unit and integration tests with the coverage gate, mutation testing on changed domain code, OpenAPI lint and breaking-change diff, executed documentation examples, fuzz smoke, image build and boot smoke, SAST, dependency review, secret scanning. A check that cannot run its input MUST fail, never pass silently.

ID Requirement Verification
DEV-020 All checks above MUST be required for merge. Ops
DEV-021 A check that finds nothing to examine (no files, no tests selected, no document) MUST fail with a message, not report success. Lint

4. Definition of Ready

An issue is ready for development when:

  1. it states the user or client question it answers, not the data it exposes;
  2. it cites the requirement ids it implements or changes, or proposes new ones;
  3. acceptance criteria are testable and name the test layer;
  4. licence impact is known (which source families, which use classes);
  5. dependencies and open decisions are resolved, or the issue is labelled blocked;
  6. it fits in one pull request or is split.

5. Definition of Done

A change is done when:

  1. the code, tests, documentation, OpenAPI document and changelog entry are in the same pull request;
  2. every acceptance criterion has a passing test at the stated layer;
  3. every required check is green, coverage and mutation targets are met;
  4. a reviewer has approved;
  5. the traceability matrix lists the test for each requirement touched;
  6. nothing in it describes how data is collected or names an internal object;
  7. for an endpoint, the endpoint Definition of Done (TEST-010) is met.
ID Requirement Verification
DEV-030 Work MUST NOT start on an issue that fails the Definition of Ready, and MUST NOT be merged before it meets the Definition of Done. Review

6. Coding standards (stack-neutral)

ID Requirement Verification
DEV-040 Code MUST be formatted by the language's standard formatter, with no configuration debates; lint warnings are errors. Lint
DEV-041 The dependency direction of the layers (domain ← application ← adapters ← entry point) MUST be enforced by the build (NFR-MAINT-001). Lint
DEV-042 Errors MUST be values or typed exceptions mapped to problem types at one place; no error MAY be swallowed silently. Review
DEV-043 Every timeout, limit, size and TTL MUST be a configuration key; literals are refused by a lint with a reasoned allow-list. Lint
DEV-044 Public names MUST come from the domain vocabulary; storage names MUST stay inside the storage adapter. Lint
DEV-045 Time MUST be handled as instants in UTC internally; conversion to Europe/Berlin happens only when rendering. Money MUST use decimal types. Geometry MUST use WGS 84. Review
DEV-046 Logging MUST be structured and go through the redacting logger only. Lint
DEV-047 Comments explain why, not what; every public function of the domain has a doc comment that cites requirement ids where relevant. Review
DEV-048 Generated code (typed queries, OpenAPI document, configuration reference) MUST be regenerated in CI; a diff fails the build. Lint

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally