Skip to content

Let the roadmap be what is open, and the code keep its reasons - #74

Merged
AndreasBur merged 1 commit into
masterfrom
roadmap-only-what-is-open
Aug 25, 2026
Merged

Let the roadmap be what is open, and the code keep its reasons#74
AndreasBur merged 1 commit into
masterfrom
roadmap-only-what-is-open

Conversation

@AndreasBur

Copy link
Copy Markdown
Owner

The file was 712 lines, and every one of the six numbered sections plus eight of the
thirteen backlog items were marked Done
. So it was a changelog with a plan inside it —
and the two read in opposite directions: a plan from the front, a changelog not at all.
Finding the five open items meant reading past 57 % of the file.

What actually made it long

Not the Done markers. The reasoning was written twice:

Decision Where it already was Where it was told again
Why the supply switch is a task, not two lines Power.h, file \details roadmap section 6
Why blanking alone would not keep the line quiet Power.h roadmap section 6
Why the hue is not stored ColorCycle.h, 142 lines of \details backlog item 5
Why the limiter asks what is shown Display.cpp, at getCurrentLimit() backlog item 5
Why the night acts on the crossing NightSwitch.h backlog item 2
Why the stored text is a fixed field Persistence.h roadmap section 2
Why a restart is asked for, not taken the RPC parser, at the case roadmap section 5

The code's version is the better one — it is at the function, in its own words, where
somebody changing that function will read it. The roadmap's copy could only fall behind.
So the finished items are now one line and a link each, pointing at the header that
explains them.

Every rationale was checked against the tree before its copy was removed. Eighteen
were searched for; the four a literal search missed were read by hand, and all four are
at their function — Version.h carries "a build that wants to say more overrides it from
the outside", Display::toggle() carries "for a button that has nothing to read the state
off", and so on. Nothing was deleted on the assumption that it must be somewhere.

Three things had no such home, so they moved

  • docs/decisions.md — the measurement that ended the Fast accessor pair. It is a
    property of a pattern spanning the whole tree, not of a class, and no header owns it.
    The platform contract already referred to it by backlog number ("the roadmap's backlog
    item 9"), which this restructure would have broken; it points at a stable anchor now.
  • docs/comparison.md — wordclock24h, ESPWortuhr and ednieuw, what each contributed,
    and "where this project is ahead". A yardstick does not change when work gets done, so
    it does not belong in a file that changes every time something ships.
  • docs/serial-commands.md — "Adding an RPC" is an instruction for somebody adding a
    command, which is what that document is for. Two sentences were added from section 4
    while it moved: ids 22–30 can be refused and carry a code, ids 34–40 cannot and all
    answer Error=0.

What the roadmap says now

136 lines. Three items next (Bluetooth transport, MQTT/Home Assistant, Ambilight), two
waiting on a board (RMT by DMA, and watching an OTA image actually be applied — the
handler is exercised against stand-ins, the loader has never been seen booting into
something it was sent), one waiting on https, one idea that needs a second front plate
before it is a plan, and the "deliberately not planned" list.

Checks

Documentation only — git diff --name-only is seven .md files. Every relative link in
the touched files was resolved against the working tree, and the #the-fast-accessor-pair
anchor against its heading. tools/documented-sizes.py passes; no new size claim was
added, and the existing ones were left exactly as written, because they describe changes
that were made and this repository's rule is that such a number is history.

712 lines of which every one of the six numbered sections and eight of the
thirteen backlog items were marked Done. The document had become a changelog
with a plan inside it, and the two read in opposite directions: one from the
front, the other not at all. Finding the five open items meant reading past
fifty-seven percent of the file.

What made it long was not the Done markers, though - it was that the reasoning
was written twice. Power.h already carries the quiescent current, why the
supply switch is a task, and why blanking alone would not keep the line quiet.
ColorCycle.h carries why the hue is not stored. Display.cpp carries, at the
function, why the limiter asks what is shown rather than what was set. Each of
those was told a second time in a roadmap item, where nobody changing the code
would look and where it could only fall behind.

So the finished items are one line and a link each, pointing at the header that
explains them. Every rationale was checked against the tree before its copy was
removed - the four that a literal search missed were read by hand and are all
at their function.

Three things had no such home and moved rather than went:

- The measurement that ended the Fast accessor pair is a property of a pattern
  spanning the tree, not of a class, and the platform contract already pointed
  at it by backlog number. It is decisions.md now, with a stable anchor, and
  the contract points there.
- The comparison with wordclock24h, ESPWortuhr and ednieuw is a yardstick, and
  a yardstick does not change when work gets done. It is comparison.md, with
  "where this project is ahead" beside it.
- "Adding an RPC" is an instruction for somebody adding a command, which is
  what serial-commands.md is, so it is at the end of that.

Sizes were left as they were written: they describe changes that were made, and
this repository's rule is that such a number is history.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@AndreasBur
AndreasBur merged commit 2f7f830 into master Aug 25, 2026
8 checks passed
@AndreasBur
AndreasBur deleted the roadmap-only-what-is-open branch August 25, 2026 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants