Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion .agents/skills/docouture-docs-versioning/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: docouture-docs-versioning
description: "How to cut a release or a prerelease on a docouture Antora documentation site scaffolded with Versioned (Full History) mode: docouture version, docs/.release-version, and the docouture-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'."
description: "How to cut a release or a prerelease on a docouture Antora documentation site scaffolded with Versioned (Full History) mode: docouture version, docs/.release-version and its alternatives (docouture version-source: github-release, tag-bump), and the docouture-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)
Expand Down Expand Up @@ -35,3 +35,14 @@ a release tag, and what the release workflow actually does).
`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).
- On a git-flow site the workflow also opens a sync pull request from the release branch
into the prerelease branch (`docs/package.json`'s `docouture.prereleaseBranch`) to carry
that bump over — merge it.
- **Where the version comes from is configurable.** `docouture.versionSource` in
`docs/package.json` is `descriptor` (the default, everything above), `github-release`
(the published GitHub Release's tag, optionally minus `docouture.versionSourcePrefix`) or
`tag-bump` (the latest `docs/v*` tag plus a bump: `docs/release` patch,
`docs/release-minor` minor, `docs/release-major` major). Only `descriptor` uses
`docs/.release-version`, the post-release bump and the git-flow sync. Show or change it
with `docouture version-source [source]`; `docouture new --mode versioned` asks for it.
See `reference/releasing.md`.
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,34 @@ advanced or touched by this step; its own `docs/src/antora.yml` permanently keep
released version, e.g. a docs typo caught after the tag went out) is a deliberate,
ordinary act, not something needing a separate flag.

## `docs/.release-version` after a release
## Version sources

`docs/package.json`'s `docouture.versionSource` picks where the version comes from;
`docouture release resolve` implements all three for both workflows (release and preview).

| source | version | notes |
| --- | --- | --- |
| `descriptor` (default) | `docs/.release-version` | the post-release bump and the git-flow sync below apply only here |
| `github-release` | tag of the published GitHub Release, minus `docouture.versionSourcePrefix` | a merged `docs/release` PR fails with a clear message; no version file |
| `tag-bump` | highest `docs/v*` tag + bump | `docs/release` patch, `docs/release-minor` minor, `docs/release-major` major (highest wins); semver-aware, prerelease tags included; the first release needs an explicit version via `workflow_dispatch`; no version file |

`docouture version-source [descriptor|github-release|tag-bump] [--prefix <p>] [--version <v>]
[--dry-run]` shows or changes it (refuses standalone sites): `descriptor` creates
`docs/.release-version` seeded with the next patch of the latest tag, the others remove it
(warning if it held a pending value), and `tag-bump` prints the `gh label create` commands
for the two extra labels. Workflows read the source at run time, so none are re-rendered, but
they run the project's installed CLI: bump `@inditextech/docouture-cli` and install first,
then `docouture upgrade` (writes `"versionSource": "descriptor"` where missing), then
optionally `docouture version-source`. `docouture doctor` shows the active source and warns
about a stray or missing `.release-version` and about a CLI without `release resolve`.

The preview comment follows the source: `descriptor` reads the file (no install),
`github-release` says the docs follow the code release without a version, and `tag-bump`
shows the version released if the PR merged now (it can change if another release lands
first). Under `tag-bump`, a run started by a published GitHub Release has no PR labels, so it
bumps patch; use `workflow_dispatch` with an explicit version for a minor or major bump there.

## `docs/.release-version` after a release (`descriptor` only)

Nothing clears it — it's bumped forward instead, except on a republish. On a genuine
forward release (the target tag was new), a final step in the workflow advances the file
Expand All @@ -84,6 +111,12 @@ on a republish (the target tag already existed): that run's target version was t
already superseded by whatever the file currently holds as the next planned target, so
bumping forward from the republished version would clobber that already-planned value.

On a **git-flow** site the bump lands on the release branch only, so the workflow's
`sync-prerelease` job opens a pull request into the prerelease branch (named by
`docs/package.json`'s `docouture.prereleaseBranch`) to carry it over — merge that PR. A
failed sync turns the run red but does not block publishing. Needs `pull-requests: write`
on the GitHub App; older sites run `docouture upgrade` once to get the job and field.

## Why there's no `docouture release` command

`docouture-release.yml`'s own steps depend on CI-only concerns a portable local CLI command
Expand Down
Loading
Loading