chore(handbook): drop legacy Maestro screenshots, source from goldens#573
Merged
Merged
Conversation
The 26 PNGs under docs/handbook/screenshots/ were Maestro Tier-3 captures that have been redundant since PR #541 introduced visual-regression goldens for every page. scripts/assemble-handbook-screenshots.sh and Dockerfile.handbook already assemble the deployed handbook image from test/goldens/screens/, so the committed PNGs are pure duplication and diverge from the live goldens (md5 mismatch). - git rm the 26 docs/handbook/screenshots/*.png - .gitignore docs/handbook/screenshots/ (local-preview-only directory) - handbook-deploy.yaml: add test/goldens/screens/** and scripts/assemble-handbook-screenshots.sh to the path-trigger so a golden bump actually rebuilds the handbook - Dockerfile.handbook header: drop the obsolete "legacy directory still copied" note - docs/handbook/README.md: replace the "scripts/run-handbook-flows.sh regenerates screenshots" workflow with the golden-driven one; rework "Einen neuen Handbook-Eintrag hinzufügen" around the goldens + assemble-script mapping; preserve the Maestro-flow guidance as optional Tier-3-smoke section
Follow-up to the previous commit's PNG removal: - .gitignore: docs/handbook/screenshots/ — local preview output only, populated by scripts/assemble-handbook-screenshots.sh - handbook-deploy.yaml path-trigger: add test/goldens/screens/** and scripts/assemble-handbook-screenshots.sh so a golden bump rebuilds the handbook (otherwise a screenshot update would be invisible to the deploy pipeline) - Dockerfile.handbook header: drop the obsolete "legacy directory still copied" note - docs/handbook/README.md: rewrite "Lokal lesen" + "Screenshots regenerieren" around the golden-driven workflow; rework "Einen neuen Handbook-Eintrag hinzufügen" around the goldens + assemble- script mapping; preserve the Maestro-flow guidance as an optional Tier-3-smoke sub-section
…eview dir Follow-up audit on the screenshot-source decoupling. The first two commits removed the duplicate Maestro PNGs and rewired the deploy trigger, but `docs/handbook/screenshots/` was still doing double-duty: golden-assembly preview output AND Tier-3 diagnostic capture sink. Two pipelines writing to the same path is exactly the ambiguity this PR is meant to remove. - scripts/run-handbook-flows.sh: capture sink moves to build/handbook-captures/ (renamed SCREENS_DIR → CAPTURES_DIR, rewrote the script header to describe Tier-3 navigation smoke + diagnostic capture, not "re-capture every handbook screenshot") - .github/workflows/tier3-handbook.yaml: artifact path follows the script - .maestro/handbook/*.yaml (26 flows): rewrite the "# Captures docs/handbook/ screenshots/NN-*.png" header to point at the Golden mapping + build/handbook-captures/ as the local capture target - README.md: tier3-handbook.yaml row now says "navigation/tap-routing smoke" with explicit note that pixel drift is owned by Visual Regression - docs/testing.md Tier-3 section: drop the "uploads docs/handbook/screenshots/ as a build artifact so reviewers can spot visual drift" line — Goldens own drift now; Tier-3 catches tap-routing, navigation, locale, iOS-build only - docs/screens.md: "Handbook" column header explains the Golden mapping + "Handbook numbering" note rewritten to lead with Goldens, Tier 3 as parallel - docs/handbook/de/index.html: rewrite the hero lede and `#architecture` section around the Golden source; new pipeline diagram is page-edit → --update-goldens on dfx01 → commit → handbook-deploy.yaml; meta description updated - scripts/assemble-handbook-screenshots.sh header: drop "legacy" wording — docs/handbook/screenshots/ is now an explicit local-preview target, not a vestigial path Verified: - bash scripts/assemble-handbook-screenshots.sh /tmp/x → 26/26 PNGs assembled - python3 yaml.safe_load on all three modified workflows → OK - bash -n on both scripts → OK - grep for stale "Captures docs/handbook/screenshots" refs → zero hits
TaprootFreak
added
the
tier3:full
- docs/handbook/de/index.html: typo "committee Repo" → "eingecheckte Repo" (renders on handbook.realunit.app — fixed before deploy) - .github/workflows/tier3-handbook.yaml: rewrite the "Why no pixel-diff" + "Why iPhone 17" header comments. Pixel drift is now explicitly owned by the Visual Regression job; the iPhone-17 rationale now references the tap-coordinate + safe-area-assertion coupling of the flows rather than the stale "screenshots captured on it" reason. - scripts/assemble-handbook-screenshots.sh: clarify the example src path is `../screenshots/NN-name.png` (relative from docs/handbook/de/). - docs/handbook/README.md: replace Anglizismus "Page-Render" with "Seitenrendering". The accepted trade-off — handbook-deploy.yaml path-trigger fires on any test/goldens/screens/** change, including the 9 non-handbook feature dirs — stays as cheap insurance against missed deploys. Documented in the PR body. Build cost is bounded by `concurrency: handbook-deploy, cancel-in-progress: false`.
- docs/handbook/de/index.html:603: golden count 57 → 68 (the 57 was the rendered-page count from PR #541's description; the actual PNG count under test/goldens/screens/ is 68 — verified via `find`). Renders on handbook.realunit.app, same risk class as the round-1 typo fix. - docs/handbook/de/index.html:638: rephrase Tier-3 / Goldens linking — previous wording read as if Tier-3 itself were documented in visual-regression-tests.md. Now: Tier-3 catches the smoke part inline, visual-regression-tests.md is the Goldens reference. - .github/workflows/tier3-handbook.yaml:3-5: stale top-of-file header sentence updated — "uploads the captured PNGs as a build artifact" is now "uploads the per-flow diagnostic captures … for forensic inspection", with forward-reference to the "Why no pixel-diff here" section that owns the full explanation.
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
1 participant
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.
Summary
Macht die visual-regression Goldens zur alleinigen Quelle der
handbook.realunit.app-Screenshots und räumt die Maestro-Tier-3-Pipeline so auf, dass keine zwei Pipelines mehr auf denselben Pfad schreiben. Bestandsaufnahme vor diesem PR:scripts/assemble-handbook-screenshots.sh+handbook-build-check.yamletabliert;Dockerfile.handbookbaut die 26 Slots seither austest/goldens/screens/zusammendocs/handbook/screenshots/, hatten gegenüber den Goldens drifted (md5 mismatch auf jedem File), und Tier-3 schrieb seine Captures in genau dieses Verzeichnis — also zwei Pipelines, ein Pfad, mehrdeutige BedeutungWas ändert sich
Commit 1 —
git rmder 26 duplizierten Maestro-PNGs unterdocs/handbook/screenshots/Commit 2 — Goldens als kanonische Quelle verdrahten
.gitignore:docs/handbook/screenshots/(jetzt reines Local-Preview-Verzeichnis, vom Assemble-Script befüllt).github/workflows/handbook-deploy.yaml: Path-Trigger umtest/goldens/screens/**+scripts/assemble-handbook-screenshots.sherweitert — Golden-Bumps lösen jetzt einen Deploy aus (das war eine latente Lücke: vorher hat ein Golden-Update den Handbook-Deploy nicht erreicht)Dockerfile.handbookHeader bereinigtdocs/handbook/README.md: Top-Statement, "Lokal lesen", "Screenshots regenerieren" und "Einen neuen Handbook-Eintrag hinzufügen" auf den golden-driven Workflow umgeschriebenCommit 3 — Konsistenz-Audit (nach User-Feedback "ich will alles professionell und konsistent")
build/handbook-captures/(klar getrennt vom Local-Preview-Pfad):scripts/run-handbook-flows.shHeader neu geschrieben +SCREENS_DIR→CAPTURES_DIR.github/workflows/tier3-handbook.yamlArtifact-Pfad nachgezogen.maestro/handbook/*.yaml(26 Flows): falsche# Captures docs/handbook/screenshots/NN-*.png-Header gegen "Tier-3 navigation smoke; handbook screenshot is the Golden mapped in ..."-Header getauschtREADME.mdWorkflow-Tabelle:tier3-handbook.yamlals "navigation/tap-routing smoke" beschrieben mit expliziter Note dass Pixel-Drift Sache vonVisual Regressionistdocs/testing.mdTier-3-Abschnitt: alte Aussage "uploads docs/handbook/screenshots/ as a build artifact so reviewers can spot visual drift" rausgenommen — Drift gehört den Goldens, Tier-3 catched Tap-Routing/Navigation/Locale/iOS-Builddocs/screens.md: "Handbook"-Spalte erklärt jetzt das Golden-Mapping; "Handbook numbering"-Note führt mit Goldens und nennt Tier 3 als parallelen Smokedocs/handbook/de/index.html: Hero-Lede +#architecture-Section komplett umgeschrieben, Pipeline-Diagramm jetzt page-edit →--update-goldensauf dfx01 → commit →handbook-deploy.yaml; Meta-Description nachgezogenscripts/assemble-handbook-screenshots.shHeader: Wort "legacy" raus —docs/handbook/screenshots/ist jetzt explizit das Local-Preview-ZielCommit 4 — Subagent-Code-Review-Findings adressiert
docs/handbook/de/index.html: Typo "committee Repo" → "eingecheckte Repo" (rendert aufhandbook.realunit.app).github/workflows/tier3-handbook.yaml: "Why no pixel-diff" + "Why iPhone 17" Header-Kommentare neu gefasst — Pixel-Drift jetzt explizit Visual-Regression-Job zugeordnet; iPhone-17-Begründung jetzt über Tap-Koordinaten + Safe-Area-Assertions statt der stalen Screenshot-Capture-Begründungscripts/assemble-handbook-screenshots.sh: Beispiel-Pfad in Header präzisiert (../screenshots/...stattscreenshots/...)docs/handbook/README.md: Anglizismus "Page-Render" → "Seitenrendering"Bewusst akzeptiertes Trade-off
Der
handbook-deploy.yaml-Path-Trigger feuert bei jeder Änderung untertest/goldens/screens/**— also auch bei den 9 Feature-Verzeichnissen, die NICHT in die 26 Handbook-Slots mappen (buy/,sell/,kyc/,hardware_connect_bitbox/,receive/,sell_bitbox/,debug_auth/, …). Über-Trigger statt fehlende Trigger ist hier bewusst gewählt: die Mapping-Tabelle inassemble-handbook-screenshots.shzu duplizieren wäre Wartungslast bei jeder Handbook-Erweiterung; einconcurrency: handbook-deploy, cancel-in-progress: false-Block serialisiert die Deploys, und das Image-Build ist <10 s + ~30 s Rollout. Worst case sind 1-2 unnötige Deploys pro Sprint — billiger als ein stiller Drift wenn jemand das Mapping erweitert und den Trigger vergisst.Verifiziert
bash scripts/assemble-handbook-screenshots.sh /tmp/x→ 26/26 PNGs sauber aus den committeten Goldens assembliert (keine fehlenden Sources)python3 yaml.safe_load(...)auf alle berührten Workflows → OKbash -nauf beide Scripts → OKgrep "Captures docs/handbook/screenshots"→ null Treffer im ganzen Repogeneral-purposeAgent, model: opus): keine BLOCKER/MAJOR; 3 MINORs + 2 NITs gefunden, alle in Commit 4 adressierttier3:fullgesetzt); Commit 4 triggert eine neue RundeOut of scope
tier3-handbook.yamlselbst — Tier 3 behält unique Wert als Navigation/Tap-Routing-Smoke + iOS-Build-/Install-Smoke +de_CH-Locale-Check. Separater Follow-up, sobald die Screenshot-Entkoppelung einen Release-Zyklus in PRD läuft.Manual test plan
handbook-deploy.yamltriggert auf den Merge-Commitdev-handbook.realunit.app: 3 repräsentative Screenshots (01-welcome.png,12-settings.png,26-terms.png) sind die Golden-Versionen, nicht die alten Maestro-Captureshandbook-capturesenthält PNGs ausbuild/handbook-captures/, nicht ausdocs/handbook/screenshots/