Skip to content

docs: ship Blog 09 + fix Social 4 verb count and resolve-chain claim#2434

Merged
bpamiri merged 4 commits intodevelopfrom
docs/social-4-fact-check-fixes
May 6, 2026
Merged

docs: ship Blog 09 + fix Social 4 verb count and resolve-chain claim#2434
bpamiri merged 4 commits intodevelopfrom
docs/social-4-fact-check-fixes

Conversation

@bpamiri
Copy link
Copy Markdown
Collaborator

@bpamiri bpamiri commented May 6, 2026

Summary

Three coordinated changes for today's wheels deploy launch (Social 4 + Blog 09):

1. Ship Blog 09 — web/content/blog/posts/wheels-deploy-kamal-port.md

Launch-day blog post, authored via the blog admin tool and exported atomically by PostExporter. Body matches the skeleton at docs/releases/blog-skeletons/09-wheels-deploy.md verbatim — 135 body lines, 24 em-dashes preserved as proper UTF-8.

CI auto-publishes: merging this PR triggers web-deploy.yml (paths watcher on web/**), which builds site-blog via Astro and deploys to Cloudflare Pages. No manual pnpm build step needed.

Note on the export: the EasyMDE-paste path corrupted UTF-8 em-dashes to MacRoman mojibake (—) on the initial save; the body was repaired by rewriting the DB column with the source skeleton bytes and re-firing the export through /jobs/runScheduledPublish. Title and summary were unaffected (different paste path). A follow-up bug for the EasyMDE charset issue is worth filing for the next blog post.

2. Slack — "~25 verbs" → "50+ commands across 9 sub-command groups"

The Slack post under-counted the actual subcommand surface by ~2x. Counted on develop:

Group Leaf paths
Top-level (init, setup, rollback, config, version, details, audit, remove, docs) 9
app (boot/start/stop/details/containers/images/logs/live/maintenance/remove) 10
proxy (boot/reboot/start/stop/restart/details/logs/remove) 8
accessory (boot/reboot/start/stop/restart/details/logs/remove) 8
build (deliver/push/pull/create/remove/details/dev) 7
registry (setup/login/logout/remove) 4
server (exec/bootstrap) 2
prune (all/images/containers) 3
lock (acquire/release/status) 3
secrets (fetch/extract/print) 3
Total 57

Replaced with (50+ commands across 9 sub-command groups). Also reworded the trailing list to make it clear that rollback/audit/details are top-level verbs, not sub-command groups.

3. GitHub Discussions — drop the "CLI overrides" claim from the resolve chain

Original Discussions copy:

${VAR} references resolve through the same lookup chain Kamal uses (CLI overrides → .kamal/secretsSystem.getenv → empty string).

Reality: every production Deploy*Cli.cfc instantiates new ConfigLoader() with no args, so envOverride is always empty in production. It exists for test injection only. No CLI flag like --env=KEY=VAL ships. Replaced with the truer 3-step user-observable chain: (.kamal/secrets → process environment variables → empty string).

4. Cleanup — fix the stale ConfigLoader.cfc line-7 comment

Line 7 listed (envOverride → System.getenv → ""), omitting .kamal/secrets. Eight lines below, the correct 4-step chain is documented. Now both match — closes the doc-drift loop opened by #2430.

Diff stat

 cli/lucli/services/deploy/config/ConfigLoader.cfc   |   2 +-
 docs/releases/blog-skeletons/social-announcements.md |   4 +-
 web/content/blog/posts/wheels-deploy-kamal-port.md  | 157 +++++++++++++++++++

The .cfc change is one line, comment-only — no functional code changes.

Test plan

  • Commit-message lint passes (docs: type, no scope, header < 100 chars per commit)
  • CI web-deploy.yml job runs on merge — builds site-blog, deploys to Cloudflare Pages
  • After deploy, https://blog.wheels.dev/wheels-deploy-kamal-port renders with em-dashes as , code blocks intact, ${VAR} shown literally
  • Spot-read Slack and Discussions blocks of Post 4 in social-announcements.md for fluency before posting

Two follow-ups from a fact-check pass on Social 4 (post #2430):

1. Slack post claimed "Full Kamal subcommand surface (~25 verbs)" — actual
   is 57 distinct command paths (9 top-level + 48 across 9 sub-command
   groups). The original count appeared to conflate top-level verbs with
   sub-command groups and undercount roughly 2x. Replaced with
   "50+ commands across 9 sub-command groups" plus an explicit list of
   the top-level rollback/audit/details verbs the original line implied
   were sub-command groups.

2. GitHub Discussions post claimed `${VAR}` interpolation chain begins
   with "CLI overrides", but no production CLI passes envOverride to
   ConfigLoader — every Deploy*Cli.cfc instantiates `new ConfigLoader()`
   with no args, so envOverride is always empty in production. The
   parameter exists for test injection only. Replaced with the truer
   3-step user-observable chain: ".kamal/secrets → process environment
   variables → empty string". Matches what someone reading
   ConfigLoader.$resolveVar will actually see.

Also fixes the stale ConfigLoader.cfc line-7 pipeline comment that
listed "envOverride → System.getenv → \"\"" — it omitted .kamal/secrets,
contradicting the line-13 comment in the same docstring that has the
correct 4-step chain. Now matches.

No code changes — the .cfc edit is a one-line comment.
@github-actions github-actions Bot added the docs label May 6, 2026
Adds the launch-day blog post (Social 4 companion) to web/content/blog/posts/.
Authored via the blog admin tool at localhost:8080; PostExporter wrote the
file atomically. Merging this PR triggers web-deploy.yml (paths watcher on
web/**), which runs the Astro build for site-blog and deploys to
Cloudflare Pages — no manual `pnpm build` needed.

Frontmatter: title, slug=wheels-deploy-kamal-port, publishedAt=2026-05-06,
tags=[deployment, wheels-4, kamal], hand-tuned excerpt. Body matches the
skeleton at docs/releases/blog-skeletons/09-wheels-deploy.md verbatim
(135 lines, all 24 em-dashes preserved as proper UTF-8 — the EasyMDE-paste
mojibake on initial save was repaired by rewriting the DB body and re-running
the export through /jobs/runScheduledPublish).

Companion social text for Slack/LinkedIn/X/Discussions is in
docs/releases/blog-skeletons/social-announcements.md (Post 4) and ships
unchanged via this same PR.
@bpamiri bpamiri changed the title docs: fix Social 4 verb count and resolve-chain claim docs: ship Blog 09 + fix Social 4 verb count and resolve-chain claim May 6, 2026
bpamiri added 2 commits May 6, 2026 08:08
The post title contains a colon ("Porting Kamal to CFML: How wheels
deploy..."), and YAML treats `title: A: B` as a nested mapping. Astro
build failed with "bad indentation of a mapping entry" at line 1 col 28
(the second colon). The skeleton at docs/releases/blog-skeletons/
09-wheels-deploy.md had this correctly quoted; the blog admin tool's
YamlFrontmatter serializer dropped the quotes during export.

Quoting the title alone is enough — js-yaml now parses the frontmatter
correctly, all other fields round-tripped cleanly (publishedAt is already
quoted, excerpt uses folded-scalar `>-` syntax, etc.).

Follow-up bug to file in wheels-dev/blog: YamlFrontmatter.serialize
should always quote string values that contain `: ` (or the broader set
of YAML reserved characters), not just publishedAt/updatedAt timestamps.
Blog 09 ("Porting Kamal to CFML") now appears as the most-recent post
on the blog index — 48,980 pixels differ vs the previous baseline,
which dates from 2026-04-26 (before this post existed).

Verified the diff is solely the new post entry: top-of-index now shows
"Porting Kamal to CFML: How wheels deploy Ships 4.0 Apps Without Ruby"
with author, May 6 2026 date, hand-tuned excerpt, and tags (#deployment,
#wheels-4, #kamal). The previously-most-recent post ("Why We Rebuilt
Our CI Pipeline") shifted to second place. No other layout, sidebar,
or theme changes — landing/guides/api/packages/sentry baselines all
matched within threshold.

Baseline image taken from the visual-regression-diffs artifact of the
prior failed run (job 74642066575) — i.e. the actual PNG that CI
rendered, not a re-shot local copy.
@bpamiri bpamiri merged commit 818e7a6 into develop May 6, 2026
10 checks passed
@bpamiri bpamiri deleted the docs/social-4-fact-check-fixes branch May 6, 2026 15:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant