From 419e84b2fa101b59c7bba28aaf7100266f2f7e25 Mon Sep 17 00:00:00 2001 From: smb Date: Sat, 5 Sep 2026 11:44:28 +0200 Subject: [PATCH] docs: require the README to keep up with what ships The README is now a product page carrying screenshots of the running application, which gives it a way to go quietly wrong that a build note never had. A screenshot ages with every layout change, not only with the feature it illustrates, and nothing in the test suite or the linter can notice. The rule binds the obligation to the change rather than to a checklist: a user-visible feature is not finished until the README shows it, and a minor release checks the README and the screenshots before the version bump. A patch needs no pass. Release notes remain the place for what is new in a version, so the README can describe the application as it is now and carry no version history. Screenshots are generated rather than collected, and the rule says so, because that is what makes the obligation cheap enough to honour. It also draws a line the capture script already respects: the script drives seams that exist, and widening an application API to make a screenshot easier changes the product for the benefit of a developer tool. The closing paragraph records why this earned a rule. Rendering the interface for #43 exposed six German strings in an English UI, a number format following the system locale instead of the interface language, and the absence of any application-level settings surface. None of them had been caught by a test, a linter or a reading review. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 7390e34..65899ad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -127,6 +127,36 @@ request that references the issue. Never push it to `main` directly. The repository is public and takes reports from other people, so the trail from a report to the change answering it has to stay visible and reviewable. +## Keeping the README honest (REQUIRED) + +The README is the product page, not a build note. A change a user can see is +not finished until the README shows the application as it now is. + +- **A user-visible feature is not done until the README shows it.** A new + stage, panel or output option means the README's description and its + screenshots match what ships. A pull request that adds one and leaves the + README describing the previous application is incomplete, the same way one + without a test is. +- **A minor release checks the README and the screenshots before the version + bump.** A patch carries corrections and needs no pass. A minor carries + something new — and the screenshots are the part that rots silently, because + they are captured from the running application and age with every layout + change, not only with the feature they illustrate. +- **Screenshots are generated, never collected.** `scripts/screenshots.py` + captures them from the real widgets, so a stale one is one command away from + being current and anyone can reproduce them. Never paste an image taken by + hand, and never let that script reach into the application: it drives + existing seams, and widening an API to make a screenshot easier is a change + to the product for the benefit of a developer tool. +- **Release notes stay the place for "what is new".** The README describes the + application as it is now and carries no version history. + +Rendering the interface is also a review. The screenshots added in #43 exposed +six German strings in an English UI, a number format following the system +locale rather than the interface, and the absence of any application-level +settings surface — none of which a test, a linter or a reading review had +caught. + ## Delegation Implementation is delegated to `codex exec -m gpt-5.6-luna -c model_reasoning_effort="xhigh"`.