/releases cannot show the release it was built for. The docs deploy and the
GitHub Release it renders are triggered by the same push, and the release is
created last — so every promotion ships a docs site that is one release behind,
until the next push to main happens to rebuild it.
Measured on the 1.1.0 promotion
|
|
Build & Deploy main to mittwald |
12:09:13 → 12:15:28 |
GitHub Release 1.1.0 created |
12:13:07 |
The next build ran while the release did not exist yet. The deployed page
listed up to 1.0.16; 1.1.0 was absent. Verified against the served page, not
inferred. A manual re-run of the deploy fixed it.
Why it is structural
getReleases() in apps/docs/src/lib/releases/githubReleases.ts fetches
api.github.com/repos/mittwald/flow/releases at build time — the page is
a static export, so whatever the build saw is frozen into the HTML.
deploy-main.yml triggers on push to main.
publish.yml triggers on the same push but creates the GitHub Release in its
last step, after npm publish. That deferral is deliberate and should stay:
pushing the release before a successful publish is what let a failed publish
ratchet a line ahead of npm.
So the deploy is racing a release that is designed to arrive later. Nothing in
the current wiring can win that race.
The same gap applies to any edit of a past release body: correcting the
1.0.0 notes updated GitHub immediately, while /releases kept serving the old
text until the next deploy.
Options
- Trigger the deploy on the release event. Add
release: [published] to
deploy-main.yml. Simplest, and it also covers edits if [edited] is
included. Costs one extra full docs build per release.
- Dispatch the deploy from
publish.yml after the release step. Keeps the
trigger explicit and ordered, but couples the two workflows.
- Fetch client-side (or via ISR) instead of at build time. Removes the race
entirely and makes edits appear without a deploy, but gives up the static
export for this page and puts a GitHub API call in the visitor's path — it
would need caching and an unauthenticated-rate-limit story.
Option 1 is the smallest change that closes the race. Option 3 is the only one
that also makes release-body edits show up on their own.
Whichever is chosen, concurrency: deploy-main-${{ github.ref }} with
cancel-in-progress: false already serialises deploys, so an extra trigger
queues rather than clashing.
/releasescannot show the release it was built for. The docs deploy and theGitHub Release it renders are triggered by the same push, and the release is
created last — so every promotion ships a docs site that is one release behind,
until the next push to
mainhappens to rebuild it.Measured on the 1.1.0 promotion
Build & Deploy main to mittwald1.1.0createdThe
next buildran while the release did not exist yet. The deployed pagelisted up to
1.0.16;1.1.0was absent. Verified against the served page, notinferred. A manual re-run of the deploy fixed it.
Why it is structural
getReleases()inapps/docs/src/lib/releases/githubReleases.tsfetchesapi.github.com/repos/mittwald/flow/releasesat build time — the page isa static export, so whatever the build saw is frozen into the HTML.
deploy-main.ymltriggers onpushtomain.publish.ymltriggers on the same push but creates the GitHub Release in itslast step, after npm publish. That deferral is deliberate and should stay:
pushing the release before a successful publish is what let a failed publish
ratchet a line ahead of npm.
So the deploy is racing a release that is designed to arrive later. Nothing in
the current wiring can win that race.
The same gap applies to any edit of a past release body: correcting the
1.0.0notes updated GitHub immediately, while/releaseskept serving the oldtext until the next deploy.
Options
release: [published]todeploy-main.yml. Simplest, and it also covers edits if[edited]isincluded. Costs one extra full docs build per release.
publish.ymlafter the release step. Keeps thetrigger explicit and ordered, but couples the two workflows.
entirely and makes edits appear without a deploy, but gives up the static
export for this page and puts a GitHub API call in the visitor's path — it
would need caching and an unauthenticated-rate-limit story.
Option 1 is the smallest change that closes the race. Option 3 is the only one
that also makes release-body edits show up on their own.
Whichever is chosen,
concurrency: deploy-main-${{ github.ref }}withcancel-in-progress: falsealready serialises deploys, so an extra triggerqueues rather than clashing.