Skip to content

Commit c2cf0af

Browse files
committed
[docs] Preserve active installer across site deploys
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th> (cherry picked from commit 99e60321d1f4255d53d7a232d8f0634e96e1c9c9)
1 parent 4c6c8fd commit c2cf0af

2 files changed

Lines changed: 51 additions & 0 deletions

File tree

‎docs/specifications/firmware/browser-flashing.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1418,3 +1418,13 @@ status; availability MUST never be inferred from the mere presence of a
14181418
manifest. Rollback changes the website's selected-release descriptor to a
14191419
previous fully qualified immutable bundle and redeploys the site. It never
14201420
mutates or partially replaces the active version directory.
1421+
1422+
Once a fully qualified public release is active, later website-only
1423+
deployments MUST carry its exact selector and immutable firmware tree forward
1424+
through authenticated retrieval and the canonical staged-release validation
1425+
path. Each website release with an active installer retains an unserved
1426+
canonical selector marker for this purpose. A deployment MUST fail before the
1427+
build if that state cannot be retrieved or validated. Transitioning an active
1428+
public installer to unavailable is a separate reviewed operation requiring an
1429+
explicit truth-valued disable flag and a production smoke test of the disabled
1430+
state; absence of staging input alone is never authorization to disable it.

‎docs/specifications/website.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,22 @@ redirect, embedded GitHub widget, remote badge, or client-side network request
116116
to present their primary information. If a link opens a new browsing context,
117117
it MUST use `noopener noreferrer`.
118118

119+
### 3.3 Public-beta social metadata
120+
121+
The home page MUST publish a local `1200 × 630` social image and large-card
122+
metadata suitable for the external beta announcement. The image MUST use the
123+
canonical prompt-chip mark and a privacy-reviewed capture of the real app
124+
described in §4. It MAY add authored brand text and framing, but MUST NOT
125+
retouch or generate the pictured app interface. Its claims MUST be limited to
126+
the current iPad external beta and the exact qualified installer profiles.
127+
128+
The social image MUST have useful alternative text, remain legible under
129+
common center crops, and make no third-party runtime request. A QR code MUST
130+
NOT be the only invitation path or be embedded in the wide social card, where
131+
platform cropping can make it unreliable. A separate local square TestFlight
132+
card MAY include the exact invitation QR, visible destination, and plain-text
133+
instructions.
134+
119135
## 4. Brand and visual contract
120136

121137
The canonical prompt-chip SVG in `app/assets/branding/` is the source asset. A
@@ -246,6 +262,25 @@ VPS origin. The origin MUST:
246262
Flexible mode; and
247263
- expose only the required web and key-authenticated administration ports.
248264

265+
After the first qualified public installer is activated, an ordinary
266+
website-only deployment MUST preserve that exact immutable selected release.
267+
The deployment obtains the selector and firmware tree from the current managed
268+
release over the authenticated deployment transport, validates them through
269+
the same staged-release and checksum gates, and embeds the selector at build
270+
time. It MUST NOT infer availability from the mere presence of a firmware
271+
directory or accept a caller-supplied selector.
272+
273+
Each release carrying an active selector MUST retain a hidden, unserved copy of
274+
the canonically validated selector as deployment state. A replacement staged
275+
public release supersedes this carry-forward state only after the full §7
276+
activation gate passes. Intentionally disabling an active installer requires a
277+
dedicated, truth-valued deployment flag; the deployment MUST reject ambiguous
278+
values and any invocation that both stages firmware and requests disablement.
279+
The public smoke test MUST prove whether the resulting `/flash` page embeds the
280+
expected active release or the explicitly disabled state. A missing selector,
281+
failed carry-forward validation, or unreviewed implicit transition from active
282+
to unavailable aborts before the website build or activation.
283+
249284
The public edge MUST redirect `www.pyble.dev`, `pyble.org`, and
250285
`www.pyble.org` to the same path and query at `https://pyble.dev`. Origin
251286
configuration SHOULD mirror those redirects as defense in depth once their DNS
@@ -347,6 +382,9 @@ The v1 site is releasable when:
347382
pictured Blocks workspace or generated Python;
348383
- the current external iPad beta invitation is exposed as an operable link and
349384
a locally served, exact-URL QR code without claiming production availability;
385+
- the home page publishes a local `1200 × 630` real-app social card with useful
386+
alternative text and large-card metadata, plus a separate local square
387+
TestFlight invitation card;
350388
- the canonical public source repository is explained in a visible
351389
MIT-licensed-source section and linked from both that section and the global
352390
footer;
@@ -369,6 +407,9 @@ The v1 site is releasable when:
369407
- the VPS deployment contract is tested, the exact checked `out/` release is
370408
active through the atomic release symlink, and an origin configuration test
371409
passes before reload;
410+
- a website-only deployment after public installer activation carries the
411+
exact selected release forward, while an intentional transition to the
412+
unavailable state requires the explicit disable flag and production smoke;
372413
- rollback confirmation survives loss of its initiating SSH transport and
373414
executes its embedded shell variables without service-manager rewriting;
374415
- every public launch-route HTML response is byte-identical to the checked

0 commit comments

Comments
 (0)