A versioned site can now choose where its docs release version comes from. The default is
unchanged, so nothing breaks, but the release workflows now call a new CLI command, so the
CLI must be updated first. Existing sites get the new workflows by running
docouture upgrade.
Do this
-
Update every
@inditextech/docouture-*package, and the CLI if you install it, to1.4.0, and install. In a scaffolded site these are pinned indocs/package.json. Do this before the next step: the generated workflows run the CLI your project installed, anddocouture-release.ymlnow callsdocouture release resolve, which older CLIs do not have. -
Run
docouture upgrade, review the diff, and commit.github/workflows/anddocs/package.json. On a versioned site it writes"versionSource": "descriptor", which keeps today’s behavior. It warns when the CLI you ran differs from the one your project installed. See CLI. -
Optional: run
docouture version-sourceto see, ordocouture version-source <source>to change, where the docs version comes from. Rundocouture doctorafterwards. It shows the active source and warns about a stray or missingdocs/.release-version.
A standalone site needs only the first two steps and has nothing to choose: it always
releases docs/stable.
What changed
-
New: three version sources. A versioned site sets
docouture.versionSourceindocs/package.json:-
descriptor(the default) readsdocs/.release-version, exactly as before, including the forward bump after each release and the git-flow sync pull request. -
github-releasetakes the version from the tag of the published GitHub Release, minus an optionaldocouture.versionSourcePrefix. The docs follow the code release. -
tag-bumptakes the latestdocs/v*tag and bumps it:docs/releasebumps patch,docs/release-minorminor anddocs/release-majormajor. Create the two extra labels once;docouture newanddocouture version-sourceprint thegh label createcommands.Under
github-releaseandtag-bumpthere is nodocs/.release-version, no post-release bump push and no sync pull request, so the release no longer needs to push to the protected release branch. See main:guides-releasing-a-documentation.adoc#version-sources.
-
-
New:
docouture version-source. Shows or changes the source, creating or removingdocs/.release-versionfor you.--dry-runpreviews it. Refuses a standalone site. -
New:
docouture release resolve. The release and preview workflows share one tested implementation of the version rules, including SemVer validation. -
New:
docouture new --version-source. Versioned mode asks which source to use. -
Changed:
docouture upgradeanddocouture doctor.upgradebackfills the default and warns on a CLI mismatch.doctorshows the active source and warns when the project’s installed CLI differs from yours or predatesrelease resolve. -
Changed: the release preview follows the source.
descriptoris unchanged and still installs nothing.github-releasesays the docs follow the code release and names no version.tag-bumpshows the version released if the pull request merged now, which can change if another release lands first. The job runs your package manager’s install only fortag-bump.
Limitations
-
Under
tag-bump, a release started by a published GitHub Release has no pull request labels to read, so it bumps patch. Useworkflow_dispatchwith an explicit version for a minor or major bump, and for the first release, when there is no tag to bump from. -
Under
github-release, a merged pull request withdocs/releasefails the release workflow with a message saying so. The preview comments that suggest addingdocs/releaseto a pull request without it still say so undergithub-release.