Publishing is a manual tag push, and the drift is what produced yesterday's 404s

[mmcky]

The pattern

Every repository in this series publishes only when someone pushes a publish* tag — this repo and the .fa, .fr and .zh-cn editions alike. Merging to main changes nothing a reader can see.

That is a deliberate design and it has real merits: publishing is expensive, and a manual gate means someone decides when the site changes. But the gate is currently the only thing scheduling publication, and in practice it drifts. State as of this morning, before today's round of tags:

Repository	Last published	Days stale
lecture-python-programming	2026-07-16	18
.fa	2026-06-19	45
.fr	2026-07-17	17
.zh-cn	2026-06-19	45

This repo had three lecture-affecting commits on main that no reader could see.

What that drift actually cost

Three things surfaced yesterday that all trace back to it, and none of which looked like a publishing problem at first:

polars 404'd in every language for four days. Added here on 2026-07-30 in #408, synced to all three translated editions and merged into each within the hour. Content and _toc.yml entries were correct everywhere. It was still 404 on all four sites — including this one — purely because nothing had been tagged since. The first read of that evidence was "the translations have not caught up", which was wrong; the English site did not have it either.

A wrong canonical stayed live for 45 days. The .zh-cn edition was emitting the English URL as its canonical on every page, telling search engines the entire Chinese edition was a duplicate of this one. Fixed in .zh-cn#80, but the fix only reached readers when that edition was finally tagged.

Divergence windows are set by tag timing, not translation speed. Sync PRs across all three editions merge in 8 minutes to 2 days, nearly always within the hour. Publishing lags by weeks. So when the language switcher advertises a page some edition does not have, the gap is almost entirely publish cadence — an inversion of the assumption I first wrote up in QuantEcon/action-translation#239, which had to be rewritten after measuring.

Yesterday's round is the counter-example: all four editions were tagged within about two minutes, all four builds succeeded in roughly six, and the switcher, the canonical fixes and polars all landed everywhere simultaneously. No divergence window opened at all. That is what good looks like, and it happened because someone did four things by hand in one sitting.

Worth considering

Not a concrete proposal — the right answer depends on how much manual control you want to keep:

• Publish on merge to main, with the tag retained for deliberate re-publishes. Maximum freshness, least control.
• Scheduled publish — a weekly or nightly cron that tags if main has moved. Bounds staleness without publishing on every merge.
• Keep it manual but make drift visible — a check that opens or comments on an issue when main is more than N days or M commits ahead of the last publish tag. Cheapest, and it addresses the actual failure, which is that nobody knew.
• Whatever is chosen, coordinate the editions. The translated sites should publish close to this one. Their content is usually ready within the hour; it is the tags that spread them weeks apart.

The last point is the one I would weight most. The individual staleness is survivable; the editions drifting apart is what produces reader-visible breakage now that they cross-link.

Related

• hreflang and switcher targets can 404 with nobody noticing — add a cross-edition reachability check action-translation#239 — asks for a check that detects switcher and hreflang targets returning 404. Largely a symptom of this; worth less if publishing becomes regular.
• Add a language-aware 404 page — the switcher can link to pages an edition does not have quantecon-book-theme#421 — language-aware 404 page, which softens the reader-facing half of the same window.