Let the roadmap be what is open, and the code keep its reasons - #74
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Power.h, file\detailsPower.hColorCycle.h, 142 lines of\detailsDisplay.cpp, atgetCurrentLimit()NightSwitch.hPersistence.hThe 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.hcarries "a build that wants to say more overrides it fromthe outside",
Display::toggle()carries "for a button that has nothing to read the stateoff", 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 theFastaccessor pair. It is aproperty 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 acommand, 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 platebefore it is a plan, and the "deliberately not planned" list.
Checks
Documentation only —
git diff --name-onlyis seven.mdfiles. Every relative link inthe touched files was resolved against the working tree, and the
#the-fast-accessor-pairanchor against its heading.
tools/documented-sizes.pypasses; no new size claim wasadded, 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.