c23c74f4 - Handbook: instructions-first walkthrough and staging-to-prod deploys - #892
Conversation
…rough images The three flex items of the walkthrough were caption-width driven, so the row fit two images and dropped the third below. Give the wrappers equal thirds (flex: 1 1 0; min-width: 0) so captions wrap under their image, and move the instructions above the images — readers get the steps first, then the visual before/after.
Retire the DEV handbook lane: the deploy-dev job, the develop trigger and the beta image tag are gone, and the paths filter is dropped on purpose so every staging merge ships handbook.realunit.app — including api- and web-sourced handbook content the filter could never see. The safety net moves to the handbook build check that gates the merge. Comments and the handbook/README docs now describe the single-lane pipeline; the former dev-handbook instance is deliberately no longer fed.
…ugh on narrow screens Review findings from the first pass: the build check now also triggers on the two handbook workflow files and the comments state what it actually gates (handbook content, not the deploy wiring); the remaining DEV/PRD phrasings in the handbook README are gone; the web-baseline pin comment reflects the single staging deploy branch; and below 700px the three walkthrough images stack as full-width rows instead of squeezing into unreadable ninths (their column layout matches the page's existing narrow-viewport behaviour, verified against a neighbouring section in a local browser render).
…CSS cascade The three remaining prose spots in the handbook page still described the staging-to-DEV split; they now match the single production deploy. The mobile stacking rules for the walkthrough move behind the base rules they override (same specificity, so source order decides — the earlier placement left flex: none dead). The build check no longer triggers on the two workflow files it cannot validate; instead its comments, the deploy header and both READMEs state precisely what the check gates (screenshot assembly, store-listing and legal sync, image build and container smoke) and that deploy wiring is only exercised by the deploy run itself. The reusable workflow's environment description drops the retired dev label.
…asset smoke The two README mentions now use the canonical four-gate phrasing, the paths-filter comment admits the self-entry, and the smoke description states what the HTTP probes actually prove: per-file existence comes from the assembly count guards, the probes only see the auth gate answer (401 arrives before nginx looks any file up — tracked in #893).
The gate bullet now carries the same container-smoke label as the job name and both READMEs, and the smoke description attributes existence proof per artifact type: the explicit count guard for screenshots, the fail-fast per-base existence check inside the image build for legal downloads — the HTTP probes prove neither.
|
Five two-dimensional review passes were run on this PR. Pass 1 (walkthrough layout + deploy rework) surfaced the deploy-only-PR gap in the build-check trigger and three test-coverage/wording points; pass 2 found three leftover DEV/PRD phrasings inside the handbook page itself, a CSS-cascade bug in the new mobile stacking rules (media query placed before the base rules it must override) and the false confidence of triggering the build check on workflow files it cannot validate — that trigger was deliberately reverted in favour of precise wording. Passes 3-5 converged the remaining wording until every gate description matches what the check actually proves per artifact type (screenshot count guard vs. fail-fast legal build; the HTTP probes prove neither — the pre-existing 401-as-existence-proof probe defect is tracked in #894). Desktop and mobile renders of the final section were verified in a local browser; the last CSS cleanup is render-identical to the verified screenshots. Note: the message of commit b571848 references #893 where #894 was meant — see the erratum section in the PR description. |
1 participant
Summary
Two handbook changes following up on #885/#889:
Walkthrough layout (user feedback on the live page)
The three images of the insider-unlock explainer rendered neither cleanly side by side nor stacked: the flex items are caption-driven wrapper divs, so two images filled the row and the third wrapped below. The block now shows the instructions first, then the three images in an equal-thirds grid with captions wrapping under their image; below 700px the walkthrough stacks as full-width rows (matching the page's existing narrow-viewport behaviour, verified against a neighbouring section). Desktop and mobile renders were verified in a local browser before pushing; the final CSS-cascade cleanup is render-identical (byte-equal screenshots).
Deploys: staging → production, DEV retired
Every push to
stagingnow deploys directly to handbook.realunit.app (:latest, PRD secrets). Thedeploy-devjob, thedeveloptrigger and the:betatag are removed, and thepaths:filter is dropped deliberately: every staging merge ships, which also re-stages the api-/web-sourced handbook content the filter could never observe. All prose that described the old staging→DEV/develop→PRD split (workflow comments, both READMEs, three spots inside the handbook page itself) now describes the single production lane, and the build-check comments state precisely what that check gates (screenshot-assembly, store-listing sync, legal-sync, image build + container smoke) versus what only the deploy run exercises (SSH/secrets/rollout).The retired dev-handbook instance keeps serving its last state until it is decommissioned on the infrastructure side (container + DNS) — intentionally out of scope for this repo. The four
DEPLOY_DEV_*repo secrets become unreferenced with this PR and can be deleted afterwards.Erratum
Commit
b571848freferences issue #893 in its message; the intended reference is #894 (pre-existing: the build check's asset smoke accepts 401 as existence proof, which the auth gate makes meaningless — found during the review passes here, tracked separately). Amending a pushed commit is out per repo policy, hence this note.