040 — A roadmap epic ticks its items as they close and leaves the file whole when all are done (#228)

Status: in progress

Why

ADR 0004 takes an item out of ROADMAP.md the moment its issue closes, to stop the file filling with history. That also removes the one thing a reader of an epic wants while it is under way: how far along it is. An epic of nine items with seven done reads as an epic of two. And the changelog gets a ### Roadmap line per item, none of which says what the epic as a whole delivered.

The manual's own roadmap is kept ticked for this reason, and tp roadmap check fails it.

The history ADR 0004 objected to is only a problem once it is all history. So a done item stays, ticked, while its epic has work left, and the epic leaves in one piece when it has none.

What changes

  • ROADMAP.md format: an item is - [ ] #N text while open and - [x] #N text once its issue is closed. A bare - #N text is still read as open, so existing roadmaps pass unchanged.
  • tp roadmap check: a ticked item is legal; ticked with an open issue, or unticked with a closed one, is reported.
  • tp roadmap archive, and the release: tick the items whose issues have closed; remove an epic (heading, description, items) only when every item in it is closed.
  • Changelog: a removed epic makes one line under the version's ### Roadmap, its name and its description, in place of a line per item.
  • docs/roadmap.md, and an ADR superseding 0004 on when an item leaves.

Acceptance

Item's issue Item in the file Rest of the epic tp roadmap check tp roadmap archive and the release
open unticked, or bare - #N any passes left as it is
open ticked any error: ticked, but #N is open left as it is
closed unticked at least one open reports #N is done, run archive ticked; stays in the file; nothing written to the changelog
closed ticked at least one open passes left as it is
closed either every item closed reports the epic is complete, run archive the epic is removed whole; one ### Roadmap line, the epic's name and description
none (- [x] text, no #N) either any error: item has no issue left as it is; it goes with its epic

An epic's description may run to several lines; the changelog line is its first sentence. An epic with no items is not complete and stays.

At code level 1 and up the epic's line travels as one fragment, changes/<n>.roadmap.md, n its first item's issue, and the release renders a roadmap fragment as - text, without #n. A story whose only fragment is that one is titled Roadmap: and the line. tp roadmap add writes - [ ] #N title.

Out of scope

Switching a dark feature on when its epic completes. An epic is often what a flag was hiding, so the release that removes the epic is the natural point to turn the flag on and for the changelog line to say so. That needs an epic to name its flag, and the flag's life is not yet defined: it is part of code level 3 (agent flow). The single changelog line per epic is built here so that story has somewhere to write.

Decisions

ADR 0009 supersedes 0004's "done means the item leaves".