Skip to content

ADR-0008: Trunk-based development with RFCs, ADRs and evergreen docs

Status: Accepted Date: 2026-09-30 Deciders: Alex Nodeland

Context

relayr is built in the open, in small steps, by a small team and agents working in parallel, as its siblings are (artifactr ADR-0014, reflexr ADR-0012, evalr ADR-0004). Its design lives in another repository's RFC (stackr RFC-0002), so the decisions and the plan need a home next to the code.

Decision

  • Trunk-based development. main is the trunk and is always releasable. Work happens on short-lived branches cut from the latest main, merged as small pull requests within a day or two. No stacked branches.
  • Squash merges with Conventional Commit titles, so main has one commit per change and git-cliff generates the changelog from history.
  • CI gates every merge (ADR-0009).
  • RFCs before substantial changes, in docs/rfcs/. Multi-PR work is tracked in its RFC's checklist; RFC-0001 carries stackr RFC-0002's phases as relayr's plan.
  • ADRs for decisions, including the decisions stackr RFC-0002 made for relayr (ADR-0001 to ADR-0007) and those made while building. Accepted ADRs are immutable; a changed decision gets a new ADR that amends or supersedes the old one.
  • Evergreen architecture docs. architecture.md describes relayr as it is, and a pull request that changes described behaviour updates it in the same pull request.

Consequences

  • Easier: every commit on main is a reviewed, releasable change, and the reasoning behind it survives in the repository.
  • Harder: every behaviour change carries a documentation obligation in the same pull request, and large work must be sliced into steps that each leave main green.