docs(site): let a release be published by hand, and say where the versions start - #1476
Merged
Conversation
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The site can version, but nothing has ever produced a second entry —
gh-pagesholds onlylatest, so the version selector has nothing to select. A version directory is created on a GitHub Release, and the site landed afterv0.6.2was cut, so the first one would not appear untilv0.6.3.Publish a version on demand
Actions → Docs → Run workflow, with a
versioninput (e.g.0.6.2) and an optional "pointlatestat it". It creates the same immutable directory a release would. The input is validated — a leadingv, or anything not shaped like1.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
src/is byte-identical between the v0.6.2 tag andmain— 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 a0.5.2directory 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.mdnow states that documented versions begin at 0.6.2, and points anyone on an older build atsaw --versionand-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.2and "pointlatestat it" ticked.mike listin the job log will then show both entries, and the selector will offer them.mkdocs build --strictclean.Closes #1475