Skip to content

docs: require the README to keep up with what ships #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smb merged 1 commit into from
Sep 5, 2026
Merged

docs: require the README to keep up with what ships #53

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`.
Expand Down
Loading