| name | docs-versioning |
| description | How to cut a release or a prerelease on this Antora documentation site, scaffolded with Versioned (Full History) mode: pdocs version, docs/.release-version, and the pdocs-release.yml workflow. USE WHEN bumping a version, cutting a release, configuring what a release tag contains, or asking how versioning works on this site. EXAMPLES: 'cut a release', 'bump the docs version', 'what does docs/.release-version do', 'how do I release a new version of the docs'. |
Docs versioning (Versioned — Full History)
This site was scaffolded with pdocs new --mode versioned. main is permanently the
prerelease/preview channel; every release is its own immutable vX.Y.Z git tag, and all
of them stay in the version dropdown forever — the shape to use when consumers pin an old
version and need its docs to keep existing unchanged.
See reference/releasing.md for the full mechanism (what each file says on main vs. on
a release tag, and what the release workflow actually does).
The short version
docs/docs/antora.yml on main always says version: prerelease,
prerelease: true — never edit this by hand to "cut" a release; it doesn't change on
main at all. A release tag gets its own copy of this file, with version: '1.2.0',
prerelease: false.pdocs version <value> is the one piece of this the CLI does for you locally — it
patches docs/docs/antora.yml's version:/prerelease: fields. Useful for testing a
version bump locally; the actual release workflow uses the same command internally.docs/.release-version holds the next planned version (e.g. 1.2.0) as plain
text. It's what a merged, docs/release-labeled pull request uses to tell the release
workflow what to tag — review it like any other file in that PR's diff.- Cutting a release happens through the
pdocs-release.yml GitHub Actions workflow
(.github/workflows/), not a local CLI command — see reference/releasing.md for why.
Trigger it either by:
- running it by hand (
workflow_dispatch), giving the target version as input, or
- merging a pull request labeled
docs/release into main — it reads the target
version from docs/.release-version.
- After a genuine new release (not a republish of an existing tag), the workflow bumps
docs/.release-version forward to the next patch version automatically and commits
that to main — you shouldn't normally need to edit it yourself except to set an
intentionally different next target (e.g. jumping to a new minor).
