Skip to content

docs(site): let a release be published by hand, and say where the versions start - #1476

Merged
Ndevu12 merged 1 commit into
mainfrom
docs/backfill-versions
Aug 17, 2026
Merged

docs(site): let a release be published by hand, and say where the versions start#1476
Ndevu12 merged 1 commit into
mainfrom
docs/backfill-versions

Conversation

@Ndevu12

@Ndevu12 Ndevu12 commented Aug 17, 2026

Copy link
Copy Markdown
Owner

The site can version, but nothing has ever produced a second entry — gh-pages holds only latest, so the version selector has nothing to select. A version directory is created on a GitHub Release, and the site landed after v0.6.2 was cut, so the first one would not appear until v0.6.3.

Publish a version on demand

Actions → Docs → Run workflow, with a version input (e.g. 0.6.2) and an optional "point latest at it". It creates the same immutable directory a release would. The input is validated — a leading v, or anything not shaped like 1.2.3, is rejected rather than deployed under a name nothing will match.

Release-triggered publishing is unchanged, and an empty input still just refreshes latest.

Why 0.6.2 is accurate, not approximate

$ git diff --stat v0.6.2..main -- src/
(no output)

src/ is byte-identical between the v0.6.2 tag and main — everything merged since has been documentation. So these pages describe that release exactly.

Why older releases are deliberately not backfilled

I checked every tag: none carries an mkdocs.yml, so there is nothing of theirs to build. The only way to produce a 0.5.2 directory would be to republish today's pages under that number — documenting flags and behaviour 0.5.2 does not have. A plausible-looking page that is wrong is worse than no page, and it is the same defect we spent this week removing.

Instead docs/index.md now states that documented versions begin at 0.6.2, and points anyone on an older build at saw --version and -h, which describe the copy they actually have.

If you would rather have the older numbers filled in anyway, say so — it is a one-line change to the workflow input — but I would be publishing something I know to be inaccurate, so I have not done it on my own judgement.

After merge

Run the workflow once with version: 0.6.2 and "point latest at it" ticked. mike list in the job log will then show both entries, and the selector will offer them.

mkdocs build --strict clean.

Closes #1475

…sions start

The site can version, but nothing has ever produced a second entry:
`gh-pages` holds only `latest`. A version directory is created on a
GitHub Release, and the site landed after v0.6.2 was cut — so the first
one would appear at v0.6.3, with nothing describing the release people
are running today.

The docs workflow can now publish a version on demand (Actions → run the
workflow, give it `0.6.2`), creating the same immutable directory a
release would, with an option to move the `latest` alias onto it. The
input is validated: a leading `v` or anything not shaped like `1.2.3` is
rejected rather than deployed under a name nothing will match.

Publishing 0.6.2 this way is accurate rather than approximate: `src/` is
byte-identical between the v0.6.2 tag and today, so these pages describe
that release exactly. Everything merged since has been documentation.

Older releases are deliberately NOT backfilled. No tag before today
carries an `mkdocs.yml`, so there is nothing of theirs to build, and
republishing today's pages under 0.5.2 would document flags and
behaviour that release does not have — a plausible-looking page that is
wrong is worse than no page. The index now says documented versions
begin at 0.6.2 and points anyone on an older build at `saw --version`
and `-h`, which describe the copy they actually have.

Closes #1475
@Ndevu12 Ndevu12 self-assigned this Aug 17, 2026
@Ndevu12 Ndevu12 added the documentation Improvements or additions to documentation label Aug 17, 2026
@Ndevu12
Ndevu12 merged commit 8662927 into main Aug 17, 2026
12 checks passed
@Ndevu12
Ndevu12 deleted the docs/backfill-versions branch August 17, 2026 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The docs site has no published versions — only latest

1 participant