Develop and extend
How-to Available

Coordinate a Multi-PR Epic

An epic changelog records what has landed, temporary transition state, the next safe slice, and blockers. It is a coordination artifact, not the source of current product invariants or backlog ownership.

For
Epic owners and reviewers
On this page
  1. Create the coordination artifact
  2. Record observed state
  3. Preserve authoritative boundaries
  4. Close cleanly
01

Create the coordination artifact

Before the first implementation PR, add docs/features/<epic-slug>/CHANGELOG.md with status, epic link, related context, current state, and newest-first changes. Every PR in the epic updates it.

02

Record observed state

Delivered describes behavior already safe to depend on. In transition names temporary compatibility or migration state. Next and Blockers describe what is actually unblocked or constrained. Link tickets and PRs rather than copying full requirements.

03

Preserve authoritative boundaries

Feature and architecture docs own current behavior. ADRs own consequential rationale. The issue tracker owns acceptance criteria, ownership, and backlog state. A changelog cannot substitute for updates to those sources when a contract changes.

04

Close cleanly

Mark the epic completed, move durable facts into authoritative docs, resolve remaining work in the issue tracker, and retain the changelog only when its migration or compatibility history remains useful.

Documentation