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.mdformat: an item is- [ ] #N textwhile open and- [x] #N textonce its issue is closed. A bare- #N textis 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".