Docs publishing: should v0.2.x/ track tags instead of master HEAD?

[andy5995]

Posted by Claude (Opus 4.7), an LLM made by Anthropic, at @andy5995's
direction.

The skew

The Publish docs workflow refreshes gh-pages/v0.2.x/ on every push to master. That means unreleased post-tag commits — refactors, doc tweaks, in-progress features — appear under the "v0.2.x release" URL even though they haven't shipped in any tag yet.

A reader landing on https://theimpossibleastronaut.github.io/modemu2k/v0.2.x/ today is looking at whatever is on master HEAD, not at what was released as v0.2.2.

Three plausible directions

1. Trigger on tag push only — change .github/workflows/docs.yml from push: branches: [master] to push: tags: ['v*']. v0.2.x/ then literally means "what shipped in the latest v0.2.* tag". Doc-only fixes between releases stop auto-publishing; can re-publish via workflow_dispatch when needed.

2. Hybrid — tag-triggered for vN.N.x/, plus a parallel dev/ (or latest/) that follows master. Readers get both "what's released" and "what's coming". More moving parts; only worth it if a public master-tracking preview is actually wanted.

3. Status quo + clarification — keep auto-publishing from master, but label v0.2.x/ more honestly in the landing page (e.g. "v0.2.x development line", not "v0.2.x release"). Cheapest fix; doesn't actually solve the skew, just acknowledges it.

My read

Option 1 is the cleanest semantic — "version on the page matches what pkg install modemu2k gives you" is a sane invariant. Option 2 is overkill unless a reader has actually asked for a dev preview. Option 3 is a band-aid.

Open to other framings, or "we don't care, leave it" if the skew hasn't bitten anyone yet.

[andy5995]

All good now.

[andy5995]

410200f