From 6a890ad8bc2b2e55302916ab31cef02feb107406 Mon Sep 17 00:00:00 2001 From: Ripley Date: Tue, 18 Aug 2026 02:49:42 -0500 Subject: [PATCH] docs: log the release and deploy scripts, and what did not transfer from PrivacyLLC's Co-Authored-By: Claude Opus 5 (1M context) --- docs/history/DEVELOPMENT_LOG.md | 71 +++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/docs/history/DEVELOPMENT_LOG.md b/docs/history/DEVELOPMENT_LOG.md index 462c854..5fa6049 100644 --- a/docs/history/DEVELOPMENT_LOG.md +++ b/docs/history/DEVELOPMENT_LOG.md @@ -46,6 +46,77 @@ sequence would have implied more. ## Entries +### 2026-08-18 — A release command, and the deploy half PrivacyLLC's deliberately omits + +Asked to model the release script on PrivacyLLC-Web's. Read theirs (30 KB, and +worth the read), took the arguments, wrote the mechanism for this project. + +**Why it was needed, in one fact.** Publishing here was `npm run docker:push` +with the version bump as a separate thing to remember. It was not remembered: +`package.json` said `0.8.3` while the four most recent commits announced *batch +0.9.0* through *batch 0.9.3*, and **no image was ever published for any of +them**. The registry's newest tag is still `v0.8.3`. Four batches of work went +out under a version naming none of them — the same failure their header +describes, arrived at independently. + +**Three things did not transfer, and each is a fact about this repository.** + +*It cannot gate on tests.* Theirs refuses to release on a half-run 1,600-test +suite. There is no suite here, so `release.sh` gates on `verify.sh` and then +says out loud that a build, a secret scan and a doc-header check are not tests +and that nothing in the gate exercised a route, a form or an API response. +Saying so is the point; a gate that implies more than it did is worse than none. + +*It must move `:dev`.* Theirs pins an immutable version in the stack. Stack 58 +follows `:dev`, so a release that only published `:vX.Y.Z` would be undeployable +here. It publishes both — which makes `:dev` a pointer and never evidence, and +`status.sh` reads the digest and version label instead. + +*The origin guard had to change shape.* Theirs validates one build arg. Here +`https://queuenorth.com` is written out in three source files and baked into +every canonical URL, `og:url`, `sitemap.xml` and `robots.txt`. So the guard asks +whether the three still agree, because a wrong origin cannot be corrected +without another build and is invisible until somebody reads the page source. + +**No prune, deliberately.** Theirs prunes because they release often. Thirteen +tags exist here in total, deleting a published image is irreversible, and the +one that matters is whichever the running container was created from — precisely +what a newest-N rule gets wrong. Their own script spends forty lines guarding +that case; not having the feature is a cheaper way to not have the bug. + +**The deploy half.** Theirs ends by saying it did not deploy and that the +Portainer edit is manual — which is exactly the gap this project has been +carrying. The template's `deploy.py` would fill it, but it builds and pushes +too, so beside `release.sh` it would mean two commands that both build and two +answers to "what is running". So `deploy.sh` does only the missing half. + +**Its most important guard is not the obvious one.** Portainer treats a stack +`PUT` as the whole desired state. Sending one without the stack's `Env` array +would strip twelve variables — the reCAPTCHA secret and the Zoho form tokens +among them — and the container would come back **healthy** while quietly +capturing no leads. That is a silent, total loss of the site's only purpose, +caused by a successful-looking deploy. It reads them, counts them, sends them +back, and refuses outright if the stack reports none. + +**Every guard was proven to refuse** rather than assumed: already-published tag, +`http` origin, trailing-slash origin, the three origin constants drifted, dirty +tree, bad flag, unpublished deploy tag, missing Portainer key, wrong stack id. + +One real bug surfaced by that testing: the image-line rewrite used `python3 -` +with a heredoc while also piping the stack file to stdin, so python tried to +execute the YAML as a script. It would have failed on the first real deploy. + +- **Closed:** none. This is tooling, not a deliverable — #212 still needs the + deploy itself. +- **Next action:** `npm run deploy -- --dry-run`, then the deploy, which needs + sign-off because it recreates the container and takes both front doors down + together. That one act ships Batch 10's accessibility fixes and closes #212. + Consider `npm run release` first so what gets deployed is a numbered version + rather than a moved pointer — `:dev` currently points at an image built before + any of today's work. +- **Blockers:** the deploy needs permission. Six issues remain blocked on the + site owner (#68, #110, #162, #213 in Batch 13; #69, #70 in Batch 14). + ### 2026-08-18 — Batch 10 shipped, and half of it was not a defect Asked to fix whatever needed fixing. Three of the six accessibility issues were