docs: name each screenshot after its tab instead of a position number - #2342
Merged
Merged
Conversation
The 43 files in docs/screenshots/ were prefixed with the tab's position on the left rail, and that prefix re-broke on every insertion: adding one tab shifts every tab below it and touches no filename. 23 of the 43 were numbered for a different tab than the one they showed, one of them by eight places, and there was no mechanical way to notice because a wrong number looks exactly like a right one (#1664). Each file is now named for its tab alone: the sidebar label lowercased, with each run of non-alphanumeric characters collapsed to one hyphen. Adding a tab now touches nothing that already exists. Three of the renames also stop the file naming a tab that no longer goes by that name — 42-debloater.png is preinstalled-apps.png after v1.109.2, 21-app-alerts.png is new-app-alerts.png, and 22-file-lock.png is file-lock-detector.png. What the convention buys is a guard. EveryScreenshotSlug_NamesARealTab asserts every filename on disk reduces from a real sidebar label, and that every gallery image's alt text names the same tab its filename does. The alt text is the half that matters most: it is what a screen-reader user gets instead of the picture, so one left on an old name has nothing else to correct it, while a sighted reader can at least read the header in the image. The cost is that renaming a tab leaves its screenshot orphaned until the file is renamed too, and that is deliberate. A renamed tab means the header rendered inside the image says the old name as well, so the file needs recapturing rather than moving, and the guard names the file that has to change. Red ritual, all four cases red for the right reason and green after restore: an orphaned filename, an alt text captioning a different tab, a tab renamed in MainWindowViewModel with no file touched, and the gallery markup ceasing to parse (which the vacuity floor catches rather than passing an empty loop). Also corrected two doc comments that had gone stale on the old scheme: the inventory guard's remarks explained why the slug check could not be written, and the tab-count regex cited a numbered filename as the shape it must not match. Refs #1664 — the 16 missing captures stay open, they need a machine that runs the application.
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.
Problem
The 43 files in
docs/screenshots/were prefixed with the tab's position on the left rail, and that prefix re-broke on every insertion: adding one tab shifts every tab below it and touches no filename. 23 of the 43 were numbered for a different tab than the one they showed, one of them by eight places — and nothing could notice, because a wrong number looks exactly like a right one.TheScreenshotInventory_MatchesWhatIsOnDisksays so in its own remarks: it deliberately did not check which screenshot covers which tab, because with a number in the name there was no rule to check against.Three filenames also named a tab that no longer goes by that name, the newest being from the previous release.
What changed
Naming. Each file is named for its tab alone: the sidebar label lowercased, with each run of non-alphanumeric characters collapsed to one hyphen.
42-debloater.png→preinstalled-apps.png,21-app-alerts.png→new-app-alerts.png,22-file-lock.png→file-lock-detector.png,16-cpu-affinity.png→cpu-core-affinity.png,14-standby-cleaner.png→standby-list-cleaner.png, and 38 more. Adding a tab now touches nothing that already exists. All 43 are pure renames —gitreports 100% similarity on every one, no image was re-encoded.A new guard, which is what the convention buys.
EveryScreenshotSlug_NamesARealTab:alttext must name the same tab its filename does;The alt text is the half that matters most. It is what someone using a screen reader gets instead of the picture, so an alt text left on an old name has nothing else to correct it, while a sighted reader can at least read the header inside the image. All 43 are correct today, which is why the assertion was free to add.
The cost, stated on purpose. Renaming a tab leaves its screenshot orphaned until the file is renamed too. That is the point rather than a side effect: a renamed tab means the header rendered inside the image says the old name as well, so the file needs recapturing and not just moving. The guard names the file that has to change, and
docs/screenshots/README.mdnow says so where a contributor will read it.Two stale doc comments. The inventory guard's remarks explained why the slug check could not be written; the tab-count regex cited
52-system-logs.pngas the shape its "tabs" requirement exists to exclude. Neither shape exists any more.Verification
Red ritual on the new guard — all four cases red for the right reason, green after restore, every file restored from saved bytes rather than from git:
alttext captioned for a different tabMainWindowViewModel, no file touchedbattery-health.pngand says to recapturedotnet build -c Releaseon app + tests: 0 errors, 0 warnings.dotnet format --verify-no-changes: clean.git grepfinds no surviving numbered screenshot reference anywhere in the tree.i/lf w/crlf, as tracked).Scope
Refs #1664 — this settles the naming half. The 16 missing captures stay open; they need a machine that runs the application.