From 90e93bf15613a5a173b75594f2f59cc40d6ce0fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Wed, 11 Nov 2026 17:43:56 +0100 Subject: [PATCH 1/4] chore: initial commit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jesus Manuel Piñeiro Cid From 06b1e7143e0950a78cc610c5126071bad76090d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Thu, 12 Nov 2026 08:17:10 +0100 Subject: [PATCH 2/4] [cli] github-release: let a docs-only PR (docs/release) republish the docs at the latest Release Under `docouture.versionSource: "github-release"`, a merged `docs/release` pull request now republishes the docs at the highest published stable GitHub Release instead of failing after the merge. - `docouture release resolve --releases `: picks the highest SemVer among the supplied Release tags, filtered by `versionSourcePrefix`, ignoring SemVer prereleases and non-SemVer tags. `--release-tag` still wins. - docouture-release.yml lists published Releases for pull_request events; docouture-release-preview.yml states the version that would be republished. - Docs: scenario-by-source table, reference-cli, v1.4.1 release note, and the docouture-docs-versioning skill. Closes #313 --- .../workflows/docouture-release-preview.yml | 41 ++++++++++--- .github/workflows/docouture-release.yml | 36 ++++++++++- AGENTS.md | 1 + .../packages/cli/src/commands/release.spec.ts | 41 ++++++++++++- code/packages/cli/src/commands/release.ts | 3 +- .../cli/src/lib/release-resolve.spec.ts | 53 ++++++++++++++++- code/packages/cli/src/lib/release-resolve.ts | 53 +++++++++++++---- .../workflows/docouture-release-preview.yml | 41 ++++++++++--- .../templates/workflows/docouture-release.yml | 36 ++++++++++- docs/src/modules/main/nav.adoc | 1 + .../guides-releasing-a-documentation.adoc | 58 +++++++++++++++++- .../src/modules/main/pages/reference-cli.adoc | 3 +- .../main/pages/release-notes/1-4-1.adoc | 42 +++++++++++++ .../main/pages/release-notes/index.adoc | 1 + .../.openspec.yaml | 2 + .../design.md | 46 +++++++++++++++ .../proposal.md | 36 +++++++++++ .../specs/docs-release-preview/spec.md | 24 ++++++++ .../specs/docs-release-resolve/spec.md | 59 +++++++++++++++++++ .../tasks.md | 39 ++++++++++++ skills/docouture-docs-versioning/SKILL.md | 3 +- .../reference/releasing.md | 20 ++++++- 22 files changed, 598 insertions(+), 41 deletions(-) create mode 100644 docs/src/modules/main/pages/release-notes/1-4-1.adoc create mode 100644 openspec/changes/github-release-docs-only-republish/.openspec.yaml create mode 100644 openspec/changes/github-release-docs-only-republish/design.md create mode 100644 openspec/changes/github-release-docs-only-republish/proposal.md create mode 100644 openspec/changes/github-release-docs-only-republish/specs/docs-release-preview/spec.md create mode 100644 openspec/changes/github-release-docs-only-republish/specs/docs-release-resolve/spec.md create mode 100644 openspec/changes/github-release-docs-only-republish/tasks.md diff --git a/.github/workflows/docouture-release-preview.yml b/.github/workflows/docouture-release-preview.yml index 27997700..ec266a93 100644 --- a/.github/workflows/docouture-release-preview.yml +++ b/.github/workflows/docouture-release-preview.yml @@ -141,22 +141,23 @@ jobs: echo "source=${source}" >> "$GITHUB_OUTPUT" echo "Version source: ${source}" - # Only `tag-bump` needs the project's own CLI here (semver ordering of - # the docs/v* tags); `descriptor` and `github-release` install nothing. + # `tag-bump` (semver ordering of the docs/v* tags) and `github-release` + # (highest published Release) need the project's own CLI here; + # `descriptor` installs nothing. - name: Setup pnpm uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4 with: package_json_file: docs/package.json - name: Setup Node - if: steps.source.outputs.source == 'tag-bump' + if: steps.source.outputs.source != 'descriptor' uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version-file: docs/package.json package-manager-cache: false - name: Install dependencies - if: steps.source.outputs.source == 'tag-bump' + if: steps.source.outputs.source != 'descriptor' run: pnpm install --frozen-lockfile # Standalone always targets 'stable'. Versioned depends on the source: @@ -164,7 +165,9 @@ jobs: # expected to have committed — same source docouture-release.yml's # pull_request trigger reads (there is no workflow_dispatch input to fall # back to here); `github-release` has no version until the code release - # publishes; `tag-bump` asks `docouture release resolve` using the tags + # publishes, or, for a docs-only `docs/release` PR, the highest published + # Release (asked of `docouture release resolve`, like `tag-bump`); + # `tag-bump` asks `docouture release resolve` using the tags # from the REST API (checkout keeps no credentials, and is shallow). - name: Resolve version id: resolve @@ -174,14 +177,21 @@ jobs: MODE: ${{ steps.detect.outputs.mode }} SOURCE: ${{ steps.source.outputs.source }} LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} + HAS_RELEASE_TYPE: ${{ (contains(join(github.event.pull_request.labels.*.name, ', '), 'release-type/') && !contains(github.event.pull_request.labels.*.name, 'skip-release')) && 'true' || 'false' }} run: | error="" if [ "$MODE" != "versioned" ]; then version="stable" tag="docs/stable" - elif [ "$SOURCE" = "github-release" ]; then + elif [ "$SOURCE" = "github-release" ] && [ "$HAS_RELEASE_TYPE" = "true" ]; then version="" tag="" + elif [ "$SOURCE" = "github-release" ]; then + releases=$(gh api --paginate "repos/${REPOSITORY}/releases" --jq '.[] | select(.draft | not) | select(.prerelease | not) | .tag_name' | paste -sd, -) + resolved=$(npx docouture release resolve --mode versioned --event pull_request --labels "$LABELS" --releases "$releases" --report) + version=$(printf '%s\n' "$resolved" | sed -n 's/^version=//p') + tag=$(printf '%s\n' "$resolved" | sed -n 's/^tag=//p') + error=$(printf '%s\n' "$resolved" | sed -n 's/^error=//p') elif [ "$SOURCE" = "tag-bump" ]; then tags=$(gh api --paginate "repos/${REPOSITORY}/git/matching-refs/tags/docs/v" --jq '.[].ref | ltrimstr("refs/tags/")' | paste -sd, -) resolved=$(npx docouture release resolve --mode versioned --event pull_request --labels "$LABELS" --tags "$tags" --report) @@ -250,7 +260,7 @@ jobs: FAIL_TIMING="If you merge it as it is, the docs release will fail." fi - if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ]; then + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ] && [ "$HAS_RELEASE_TYPE" = "true" ]; then gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body " ### :information_source: The docs are released with the code release This site's docs version source is \`github-release\`: the docs site is published when the code release publishes a GitHub Release, never when a Pull Request merges. No version can be shown here, and the \`docs/release\` label does **not** release the docs on merge. @@ -271,6 +281,17 @@ jobs: exit 0 fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ] && [ -n "$ERROR" ]; then + gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body " + ### :x: Docs release will fail: no published Release to republish + This site's docs version source is \`github-release\`, and no published stable GitHub Release was found (a Release matching \`docouture.versionSourcePrefix\` when one is set). A docs-only \`docs/release\` Pull Request republishes the docs at the highest published Release. + + ${FAIL_TIMING} + + **Before merging:** publish a Release first, or release the docs manually with \`docouture-release\` from the Actions tab, giving an explicit version." + exit 0 + fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "descriptor" ] && [ -z "$VERSION" ]; then gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body " ### :x: Docs release will fail: no target version @@ -325,6 +346,12 @@ jobs: fi fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ] && [ "$HAS_RELEASE_TYPE" != "true" ]; then + MESSAGE="${MESSAGE} + + This republishes the highest published stable GitHub Release (matching \`docouture.versionSourcePrefix\` when one is set), **if this Pull Request merged now**. It can change if another Release publishes first." + fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "tag-bump" ]; then MESSAGE="${MESSAGE} diff --git a/.github/workflows/docouture-release.yml b/.github/workflows/docouture-release.yml index 4c9f5a20..a6906437 100644 --- a/.github/workflows/docouture-release.yml +++ b/.github/workflows/docouture-release.yml @@ -58,8 +58,9 @@ name: docouture-release # Version source (versioned only): where a release's version comes from is the # site's `docouture.versionSource` in docs/package.json, resolved by `docouture # release resolve` — `descriptor` (default: docs/.release-version, as described -# above), `github-release` (the published GitHub Release's tag) or `tag-bump` -# (the latest docs/v* tag plus a bump: `docs/release` patch, +# above), `github-release` (the published GitHub Release's tag; a docs-only +# `docs/release` pull request republishes the highest published stable Release) +# or `tag-bump` (the latest docs/v* tag plus a bump: `docs/release` patch, # `docs/release-minor` minor, `docs/release-major` major). Only `descriptor` # runs the descriptor bump and the git-flow sync below. Under `tag-bump` a # `release: published` run has no pull request labels to read, so it bumps @@ -298,12 +299,37 @@ jobs: echo "mode=${mode}" >> "$GITHUB_OUTPUT" echo "Detected ${mode} (antora-playbook.yml: ${line})" + # A pull request carries no version under `github-release`, so a docs-only + # `docs/release` merge republishes the highest published Release instead: + # list the repository's non-draft, non-prerelease Releases here and let + # `docouture release resolve` filter by `versionSourcePrefix` and pick the + # highest SemVer (the order of this list does not matter). Other events and + # other version sources skip the lookup. + - name: List published Releases + id: releases + if: github.event_name == 'pull_request' + env: + GH_TOKEN: ${{ github.token }} + REPOSITORY: ${{ github.repository }} + run: | + source=$(node -p "require('./package.json').docouture?.versionSource ?? 'descriptor'") + if [ "$source" != "github-release" ]; then + echo "tags=" >> "$GITHUB_OUTPUT" + exit 0 + fi + + tags=$(gh api --paginate "repos/${REPOSITORY}/releases" \ + --jq '.[] | select(.draft | not) | select(.prerelease | not) | .tag_name' | paste -sd, -) + echo "tags=${tags}" >> "$GITHUB_OUTPUT" + echo "Published Releases: ${tags:-none}" + # Where the target version comes from is decided by `docouture release # resolve`, which reads the site's `docouture.versionSource` from # docs/package.json: `descriptor` (default) uses the workflow_dispatch # input if a person typed one, else the docs/.release-version file the # merged PR committed; `github-release` uses the published Release's - # tag; `tag-bump` bumps the latest docs/v* tag by the PR's + # tag, or the highest published stable Release for a docs-only PR; + # `tag-bump` bumps the latest docs/v* tag by the PR's # `docs/release[-minor|-major]` label. Standalone always targets # `stable`. The command also validates it (present, SemVer, # not 'stable') and fails here, before any tag is pushed below — a @@ -316,6 +342,7 @@ jobs: EVENT: ${{ github.event_name }} DISPATCH_VERSION: ${{ inputs.version }} RELEASE_TAG: ${{ github.event.release.tag_name }} + RELEASES: ${{ steps.releases.outputs.tags }} LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} run: | args=(release resolve --mode "$MODE" --event "$EVENT" --labels "$LABELS") @@ -325,6 +352,9 @@ jobs: if [ -n "$RELEASE_TAG" ]; then args+=(--release-tag "$RELEASE_TAG") fi + if [ -n "$RELEASES" ]; then + args+=(--releases "$RELEASES") + fi resolved=$(npx docouture "${args[@]}") echo "$resolved" >> "$GITHUB_OUTPUT" diff --git a/AGENTS.md b/AGENTS.md index c8e50449..991e4f39 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -153,6 +153,7 @@ issue belongs to. | structure.adoc | `code/README.md`, workspace `packages/` layout | current | | guides-branching-model.adoc | `code/packages/cli/templates/workflows/*.yml` | current | | guides-releasing-a-documentation.adoc | `code/packages/cli/templates/workflows/docouture-release.yml`, `docouture-release-preview.yml` | current | +| release-notes/1-4-1.adoc (v1.4.1 entry) | manual (hand-written: github-release docs-only republish, `--releases` flag) | current | | release-notes/1-4-0.adoc (v1.4.0 entry) | manual (hand-written: version sources, upgrade order, limitations) | current | | release-notes/1-3-2.adoc (v1.3.2 entry) | manual (hand-written: combined-release preview wording and upgrade steps) | current | | release-notes/1-3-1.adoc (v1.3.1 entry) | manual (hand-written: handlebars security floor and upgrade steps) | current | diff --git a/code/packages/cli/src/commands/release.spec.ts b/code/packages/cli/src/commands/release.spec.ts index e195f79c..69f8a4b5 100644 --- a/code/packages/cli/src/commands/release.spec.ts +++ b/code/packages/cli/src/commands/release.spec.ts @@ -126,7 +126,7 @@ describe('runRelease resolve', () => { expect(out()).toContain('uses_descriptor=false') }) - it('fails a docs/release pull request under github-release', async () => { + it('fails a docs/release pull request under github-release without Releases', async () => { await writeSource({ versionSource: 'github-release' }) const argv = [ 'resolve', @@ -143,6 +143,45 @@ describe('runRelease resolve', () => { expect(errorSpy.mock.calls.flat().join('\n')).toContain('github-release') }) + it('republishes the highest injected Release for a docs/release pull request', async () => { + await writeSource({ versionSource: 'github-release', versionSourcePrefix: 'docs-site@' }) + const argv = [ + 'resolve', + '--mode', + 'versioned', + '--event', + 'pull_request', + '--labels', + 'docs/release', + '--releases', + 'api@9.0.1,docs-site@1.3.9\ndocs-site@1.4.0', + '--dir', + dir, + ] + expect(await runRelease(argv)).toBe(0) + expect(out()).toContain('version=1.4.0') + expect(out()).toContain('tag=docs/v1.4.0') + expect(out()).toContain('uses_descriptor=false') + }) + + it('reports a missing Release in --report mode with exit 0', async () => { + await writeSource({ versionSource: 'github-release' }) + const argv = [ + 'resolve', + '--mode', + 'versioned', + '--event', + 'pull_request', + '--labels', + 'docs/release', + '--report', + '--dir', + dir, + ] + expect(await runRelease(argv)).toBe(0) + expect(out()).toContain('error=unsupported') + }) + it('bumps tag-bump from real git tags and the label list', async () => { await writeSource({ versionSource: 'tag-bump' }) git('init', '-q') diff --git a/code/packages/cli/src/commands/release.ts b/code/packages/cli/src/commands/release.ts index a3dda466..bc4468c5 100644 --- a/code/packages/cli/src/commands/release.ts +++ b/code/packages/cli/src/commands/release.ts @@ -21,7 +21,7 @@ import { } from '../lib/release-resolve.js' const USAGE = - 'usage: docouture release resolve --mode [--version ] [--event ] [--release-tag ] [--labels ] [--tags ] [--report] [--dir ]' + 'usage: docouture release resolve --mode [--version ] [--event ] [--release-tag ] [--labels ] [--tags ] [--releases ] [--report] [--dir ]' type Flags = Record @@ -114,6 +114,7 @@ async function runResolve(argv: string[]): Promise { source, event: stringFlag(flags, 'event'), releaseTag: stringFlag(flags, 'release-tag'), + releases: listFlag(stringFlag(flags, 'releases'), /[,\n]/) ?? [], prefix: declaration.prefix ?? undefined, labels: listFlag(stringFlag(flags, 'labels'), /,/) ?? [], tags: await resolveTags(mode, source, listFlag(stringFlag(flags, 'tags'), /[,\n]/), repoRoot), diff --git a/code/packages/cli/src/lib/release-resolve.spec.ts b/code/packages/cli/src/lib/release-resolve.spec.ts index fe6002a6..d4bf054d 100644 --- a/code/packages/cli/src/lib/release-resolve.spec.ts +++ b/code/packages/cli/src/lib/release-resolve.spec.ts @@ -145,10 +145,61 @@ describe('resolveRelease', () => { expect(r.error?.kind).toBe('invalid') }) - it('fails a docs/release pull request', () => { + it('fails a docs/release pull request with no Release available', () => { const r = resolveRelease({ ...base, event: 'pull_request', labels: ['docs/release'] }) expect(r.error?.kind).toBe('unsupported') expect(r.error?.message).toContain('github-release') + expect(r.error?.message).toContain('published GitHub Release') + }) + + describe('docs-only pull request', () => { + const pr = { ...base, event: 'pull_request', labels: ['docs/release'] } as const + + it('republishes the highest Release', () => { + const r = resolveRelease({ ...pr, releases: ['1.3.9', '1.4.0', '1.2.0'] }) + expect(r).toMatchObject({ version: '1.4.0', tag: 'docs/v1.4.0', usesDescriptor: false }) + expect(r.error).toBeUndefined() + }) + + it('picks the highest SemVer, not the newest', () => { + expect(resolveRelease({ ...pr, releases: ['1.3.9', '1.4.0'] }).version).toBe('1.4.0') + expect(resolveRelease({ ...pr, releases: ['1.4.0', '1.3.9'] }).version).toBe('1.4.0') + }) + + it('lets the prefix select the package', () => { + const r = resolveRelease({ + ...pr, + prefix: 'docs-site@', + releases: ['api@9.0.1', 'docs-site@1.4.0', 'docs-site@1.3.9'], + }) + expect(r.version).toBe('1.4.0') + }) + + it('ignores prereleases and non-SemVer tags', () => { + expect(resolveRelease({ ...pr, releases: ['1.5.0-rc.1', 'nightly', '1.4.0'] }).version).toBe('1.4.0') + }) + + it('names the prefix and the count when nothing matches', () => { + const r = resolveRelease({ ...pr, prefix: 'docs-site@', releases: ['api@9.0.1'] }) + expect(r.error?.kind).toBe('missing') + expect(r.error?.message).toContain('docs-site@') + expect(r.error?.message).toContain('1 published release ') + }) + + it('lets a release tag win over the supplied releases', () => { + const r = resolveRelease({ ...pr, releaseTag: '1.5.0', releases: ['1.9.0'] }) + expect(r.version).toBe('1.5.0') + }) + + it('lets an explicit version win', () => { + const r = resolveRelease({ ...pr, explicit: '2.0.0', releases: ['1.9.0'] }) + expect(r.version).toBe('2.0.0') + }) + + it('does not use releases without the docs/release label', () => { + const r = resolveRelease({ ...base, event: 'pull_request', labels: [], releases: ['1.9.0'] }) + expect(r.error?.kind).toBe('missing') + }) }) it('lets an explicit version win, even for a labelled pull request', () => { diff --git a/code/packages/cli/src/lib/release-resolve.ts b/code/packages/cli/src/lib/release-resolve.ts index 9fb9e132..4ac3002c 100644 --- a/code/packages/cli/src/lib/release-resolve.ts +++ b/code/packages/cli/src/lib/release-resolve.ts @@ -4,7 +4,7 @@ 'use strict' -import { bumpVersion, highestSemver, isSemver } from './semver.js' +import { bumpVersion, highestSemver, isSemver, parseSemver } from './semver.js' export type ReleaseMode = 'versioned' | 'standalone' @@ -50,6 +50,9 @@ export interface ResolveInput { event?: string // Tag of the published GitHub Release (github-release). releaseTag?: string + // Tags of the repository's published, non-draft, non-prerelease GitHub + // Releases (github-release, docs-only pull request). Order is irrelevant. + releases?: string[] // `docouture.versionSourcePrefix`, stripped from releaseTag (github-release). prefix?: string // Labels on the merged pull request (tag-bump, and the github-release guard). @@ -113,21 +116,50 @@ export function resolveDescriptor(input: ResolveInput): ReleaseResolution { return result } +// Highest stable SemVer among published Release tags: only tags that start +// with the prefix count, the prefix is stripped, and anything that is not +// SemVer or is a SemVer prerelease is ignored. +function highestRelease(releases: string[], prefix: string): string | null { + const versions = releases + .filter((tag) => tag.startsWith(prefix)) + .map((tag) => tag.slice(prefix.length)) + .filter((version) => (parseSemver(version)?.prerelease.length ?? 1) === 0) + return highestSemver(versions) +} + // `github-release`: the docs follow the code release, so the version is the -// published release tag minus an optional prefix. +// published release tag minus an optional prefix. A docs-only pull request has +// no release tag; it republishes the highest published Release instead. function resolveGithubRelease(input: ResolveInput, explicit: string): ReleaseResolution { - const sourceLabel = explicit ? INPUT_SOURCE : 'release tag' - if (!explicit && input.event === 'pull_request' && (input.labels ?? []).includes(RELEASE_LABEL)) { - return finish('', 'github-release', false, { - kind: 'unsupported', - value: RELEASE_LABEL, - message: `this site's docs version source is 'github-release': docs are released when the code release publishes a GitHub Release, not when a '${RELEASE_LABEL}' pull request merges — remove the label or switch source with 'docouture version-source'`, - }) + const prefix = input.prefix ?? '' + const tag = input.releaseTag?.trim() ?? '' + const isDocsPullRequest = input.event === 'pull_request' && (input.labels ?? []).includes(RELEASE_LABEL) + + if (!explicit && tag === '' && isDocsPullRequest) { + const releases = (input.releases ?? []).map((r) => r.trim()).filter((r) => r !== '') + if (releases.length === 0) { + return finish('', 'github-release', false, { + kind: 'unsupported', + value: RELEASE_LABEL, + message: `this site's docs version source is 'github-release': a '${RELEASE_LABEL}' pull request republishes the docs at the highest published GitHub Release, and none was found — publish a Release first, or start docouture-release manually with an explicit version`, + }) + } + const latest = highestRelease(releases, prefix) + if (latest === null) { + const count = `${releases.length} published ${releases.length === 1 ? 'release' : 'releases'}` + const scope = prefix === '' ? '' : ` starting with the configured docouture.versionSourcePrefix '${prefix}'` + return finish('', 'github-release', false, { + kind: 'missing', + value: prefix, + message: `no stable SemVer GitHub Release tag${scope} was found among ${count} considered — publish a Release first, or start docouture-release manually with an explicit version`, + }) + } + return finish(latest, 'latest GitHub Release', false) } + const sourceLabel = explicit ? INPUT_SOURCE : 'release tag' let version = explicit if (!explicit) { - const tag = input.releaseTag?.trim() ?? '' if (tag === '') { return finish('', sourceLabel, false, { kind: 'missing', @@ -136,7 +168,6 @@ function resolveGithubRelease(input: ResolveInput, explicit: string): ReleaseRes "version source 'github-release' reads the published GitHub Release tag, and none was given — run it from a release event or pass an explicit version", }) } - const prefix = input.prefix ?? '' if (prefix !== '' && !tag.startsWith(prefix)) { return finish(tag, sourceLabel, false, { kind: 'prefix', diff --git a/code/packages/cli/templates/workflows/docouture-release-preview.yml b/code/packages/cli/templates/workflows/docouture-release-preview.yml index 55f9abea..fdc1acdb 100644 --- a/code/packages/cli/templates/workflows/docouture-release-preview.yml +++ b/code/packages/cli/templates/workflows/docouture-release-preview.yml @@ -141,18 +141,19 @@ jobs: echo "source=${source}" >> "$GITHUB_OUTPUT" echo "Version source: ${source}" - # Only `tag-bump` needs the project's own CLI here (semver ordering of - # the docs/v* tags); `descriptor` and `github-release` install nothing. + # `tag-bump` (semver ordering of the docs/v* tags) and `github-release` + # (highest published Release) need the project's own CLI here; + # `descriptor` installs nothing. # __DOCOUTURE_PM_SETUP_STEP__ - name: Setup Node - if: steps.source.outputs.source == 'tag-bump' + if: steps.source.outputs.source != 'descriptor' uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version-file: docs/package.json package-manager-cache: false - name: Install dependencies - if: steps.source.outputs.source == 'tag-bump' + if: steps.source.outputs.source != 'descriptor' run: __DOCOUTURE_INSTALL_CI__ # Standalone always targets 'stable'. Versioned depends on the source: @@ -160,7 +161,9 @@ jobs: # expected to have committed — same source docouture-release.yml's # pull_request trigger reads (there is no workflow_dispatch input to fall # back to here); `github-release` has no version until the code release - # publishes; `tag-bump` asks `docouture release resolve` using the tags + # publishes, or, for a docs-only `docs/release` PR, the highest published + # Release (asked of `docouture release resolve`, like `tag-bump`); + # `tag-bump` asks `docouture release resolve` using the tags # from the REST API (checkout keeps no credentials, and is shallow). - name: Resolve version id: resolve @@ -170,14 +173,21 @@ jobs: MODE: ${{ steps.detect.outputs.mode }} SOURCE: ${{ steps.source.outputs.source }} LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} + HAS_RELEASE_TYPE: ${{ (contains(join(github.event.pull_request.labels.*.name, ', '), 'release-type/') && !contains(github.event.pull_request.labels.*.name, 'skip-release')) && 'true' || 'false' }} run: | error="" if [ "$MODE" != "versioned" ]; then version="stable" tag="docs/stable" - elif [ "$SOURCE" = "github-release" ]; then + elif [ "$SOURCE" = "github-release" ] && [ "$HAS_RELEASE_TYPE" = "true" ]; then version="" tag="" + elif [ "$SOURCE" = "github-release" ]; then + releases=$(gh api --paginate "repos/${REPOSITORY}/releases" --jq '.[] | select(.draft | not) | select(.prerelease | not) | .tag_name' | paste -sd, -) + resolved=$(npx docouture release resolve --mode versioned --event pull_request --labels "$LABELS" --releases "$releases" --report) + version=$(printf '%s\n' "$resolved" | sed -n 's/^version=//p') + tag=$(printf '%s\n' "$resolved" | sed -n 's/^tag=//p') + error=$(printf '%s\n' "$resolved" | sed -n 's/^error=//p') elif [ "$SOURCE" = "tag-bump" ]; then tags=$(gh api --paginate "repos/${REPOSITORY}/git/matching-refs/tags/docs/v" --jq '.[].ref | ltrimstr("refs/tags/")' | paste -sd, -) resolved=$(npx docouture release resolve --mode versioned --event pull_request --labels "$LABELS" --tags "$tags" --report) @@ -246,7 +256,7 @@ jobs: FAIL_TIMING="If you merge it as it is, the docs release will fail." fi - if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ]; then + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ] && [ "$HAS_RELEASE_TYPE" = "true" ]; then gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body " ### :information_source: The docs are released with the code release This site's docs version source is \`github-release\`: the docs site is published when the code release publishes a GitHub Release, never when a Pull Request merges. No version can be shown here, and the \`docs/release\` label does **not** release the docs on merge. @@ -267,6 +277,17 @@ jobs: exit 0 fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ] && [ -n "$ERROR" ]; then + gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body " + ### :x: Docs release will fail: no published Release to republish + This site's docs version source is \`github-release\`, and no published stable GitHub Release was found (a Release matching \`docouture.versionSourcePrefix\` when one is set). A docs-only \`docs/release\` Pull Request republishes the docs at the highest published Release. + + ${FAIL_TIMING} + + **Before merging:** publish a Release first, or release the docs manually with \`docouture-release\` from the Actions tab, giving an explicit version." + exit 0 + fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "descriptor" ] && [ -z "$VERSION" ]; then gh pr comment "$PR_NUMBER" --repo "$REPOSITORY" --body " ### :x: Docs release will fail: no target version @@ -321,6 +342,12 @@ jobs: fi fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "github-release" ] && [ "$HAS_RELEASE_TYPE" != "true" ]; then + MESSAGE="${MESSAGE} + + This republishes the highest published stable GitHub Release (matching \`docouture.versionSourcePrefix\` when one is set), **if this Pull Request merged now**. It can change if another Release publishes first." + fi + if [ "$MODE" = "versioned" ] && [ "$SOURCE" = "tag-bump" ]; then MESSAGE="${MESSAGE} diff --git a/code/packages/cli/templates/workflows/docouture-release.yml b/code/packages/cli/templates/workflows/docouture-release.yml index da9a335f..b8fb9072 100644 --- a/code/packages/cli/templates/workflows/docouture-release.yml +++ b/code/packages/cli/templates/workflows/docouture-release.yml @@ -58,8 +58,9 @@ name: docouture-release # Version source (versioned only): where a release's version comes from is the # site's `docouture.versionSource` in docs/package.json, resolved by `docouture # release resolve` — `descriptor` (default: docs/.release-version, as described -# above), `github-release` (the published GitHub Release's tag) or `tag-bump` -# (the latest docs/v* tag plus a bump: `docs/release` patch, +# above), `github-release` (the published GitHub Release's tag; a docs-only +# `docs/release` pull request republishes the highest published stable Release) +# or `tag-bump` (the latest docs/v* tag plus a bump: `docs/release` patch, # `docs/release-minor` minor, `docs/release-major` major). Only `descriptor` # runs the descriptor bump and the git-flow sync below. Under `tag-bump` a # `release: published` run has no pull request labels to read, so it bumps @@ -294,12 +295,37 @@ jobs: echo "mode=${mode}" >> "$GITHUB_OUTPUT" echo "Detected ${mode} (antora-playbook.yml: ${line})" + # A pull request carries no version under `github-release`, so a docs-only + # `docs/release` merge republishes the highest published Release instead: + # list the repository's non-draft, non-prerelease Releases here and let + # `docouture release resolve` filter by `versionSourcePrefix` and pick the + # highest SemVer (the order of this list does not matter). Other events and + # other version sources skip the lookup. + - name: List published Releases + id: releases + if: github.event_name == 'pull_request' + env: + GH_TOKEN: ${{ github.token }} + REPOSITORY: ${{ github.repository }} + run: | + source=$(node -p "require('./package.json').docouture?.versionSource ?? 'descriptor'") + if [ "$source" != "github-release" ]; then + echo "tags=" >> "$GITHUB_OUTPUT" + exit 0 + fi + + tags=$(gh api --paginate "repos/${REPOSITORY}/releases" \ + --jq '.[] | select(.draft | not) | select(.prerelease | not) | .tag_name' | paste -sd, -) + echo "tags=${tags}" >> "$GITHUB_OUTPUT" + echo "Published Releases: ${tags:-none}" + # Where the target version comes from is decided by `docouture release # resolve`, which reads the site's `docouture.versionSource` from # docs/package.json: `descriptor` (default) uses the workflow_dispatch # input if a person typed one, else the docs/.release-version file the # merged PR committed; `github-release` uses the published Release's - # tag; `tag-bump` bumps the latest docs/v* tag by the PR's + # tag, or the highest published stable Release for a docs-only PR; + # `tag-bump` bumps the latest docs/v* tag by the PR's # `docs/release[-minor|-major]` label. Standalone always targets # `stable`. The command also validates it (present, SemVer, # not 'stable') and fails here, before any tag is pushed below — a @@ -312,6 +338,7 @@ jobs: EVENT: ${{ github.event_name }} DISPATCH_VERSION: ${{ inputs.version }} RELEASE_TAG: ${{ github.event.release.tag_name }} + RELEASES: ${{ steps.releases.outputs.tags }} LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} run: | args=(release resolve --mode "$MODE" --event "$EVENT" --labels "$LABELS") @@ -321,6 +348,9 @@ jobs: if [ -n "$RELEASE_TAG" ]; then args+=(--release-tag "$RELEASE_TAG") fi + if [ -n "$RELEASES" ]; then + args+=(--releases "$RELEASES") + fi resolved=$(npx docouture "${args[@]}") echo "$resolved" >> "$GITHUB_OUTPUT" diff --git a/docs/src/modules/main/nav.adoc b/docs/src/modules/main/nav.adoc index c9c92720..7d629804 100644 --- a/docs/src/modules/main/nav.adoc +++ b/docs/src/modules/main/nav.adoc @@ -38,6 +38,7 @@ * xref:main:additional-information-overview.adoc[Overview] * xref:main:changelog/index.adoc[Changelog] * xref:main:release-notes/index.adoc[Release notes] +** xref:main:release-notes/1-4-1.adoc[v1.4.1] ** xref:main:release-notes/1-4-0.adoc[v1.4.0] ** xref:main:release-notes/1-3-2.adoc[v1.3.2] ** xref:main:release-notes/1-3-1.adoc[v1.3.1] diff --git a/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc b/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc index 6b400f65..abded03c 100644 --- a/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc +++ b/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc @@ -70,7 +70,7 @@ pull request below). A versioned site can instead choose another source with |`docs/.release-version`, committed by the release pull request. The forward-bump and the git-flow sync described here apply only to this source. |`github-release` -|The tag of the published GitHub Release, minus the optional `docouture.versionSourcePrefix` (for example `docs-site@`). The docs follow the code release. A merged `docs/release` pull request fails with a message saying so. +|The tag of the published GitHub Release, minus the optional `docouture.versionSourcePrefix` (for example `docs-site@`). The docs follow the code release. A merged docs-only `docs/release` pull request republishes the docs at the *highest* published stable Release (see <>). |`tag-bump` |The highest existing `docs/v*` tag plus a bump: `docs/release` bumps patch, `docs/release-minor` minor and `docs/release-major` major (the highest wins when several are present). The first release has no tag to bump from, so run `docouture-release` manually with an explicit version. @@ -83,8 +83,9 @@ commands for the two extra labels, which you create once. `docouture release res implements the rules for both workflows. * The preview comment follows the source: `descriptor` reads the file (no dependency - install), `github-release` says the docs follow the code release without naming a - version, and `tag-bump` shows the version released *if the pull request merged now*, which + install), `github-release` shows the version a docs-only pull request would republish + (or says the docs follow the code release when the pull request also carries + `release-type/*`), and `tag-bump` shows the version released *if the pull request merged now*, which can change if another release lands first. * Under `tag-bump`, a run started by a published GitHub Release has no pull request labels to read, so it bumps patch. Use `workflow_dispatch` with an explicit version for @@ -96,6 +97,57 @@ implements the rules for both workflows. warns about a stray or missing `docs/.release-version` and about a project CLI that predates `release resolve`. +[#github-release-republish] +=== Republishing docs under `github-release` + +A pull request carries no version under `github-release`, so a merged docs-only pull +request labelled `docs/release` takes it from the repository's published GitHub Releases +instead: the *highest SemVer* version among them, not the newest one (a backport +released after `1.4.0` does not make the docs go back to `1.3.9`). The workflow lists the +non-draft, non-prerelease Releases and `docouture release resolve` then: + +* keeps only tags that start with `docouture.versionSourcePrefix` (all tags when none is + set), so a repository that publishes several packages picks the right one; +* strips the prefix and ignores anything that is not SemVer, or is a SemVer prerelease such + as `1.5.0-rc.1`; +* republishes `docs/v`. The tag is force-recreated like any republish, and there + is no descriptor bump or git-flow sync. + +Without a prefix, the highest tag across all of the repository's Releases wins, so declare +`docouture.versionSourcePrefix` on a repository that publishes more than one package. If no +Release matches, the merge fails with a message naming the prefix and how many releases were +considered; the preview comment warns about it first. + +[#release-scenarios] +=== Which trigger releases what + +What a merged pull request, or a manual run, releases under each version source. "Code release" +means the pull request carries a `release-type/*` label (without `skip-release`) and the code +release publishes a GitHub Release; see <>. + +[cols="2,3,3,3"] +|=== +|Scenario |`github-release` |`tag-bump` |`descriptor` (default) + +|*Pull request with code and docs* (`release-type/*`, with or without `docs/release`) +|Not released on merge. When the code release publishes a Release, the docs are released at *that Release's tag*. +|Not released on merge. When the code release publishes a Release, the docs are released at the latest `docs/v*` tag *plus a patch bump* (a Release event carries no labels). +|Not released on merge. When the code release publishes a Release, the docs are released at the version in `docs/.release-version`. + +|*Pull request with only docs* (`docs/release`, no `release-type/*`) +|Released on merge, republishing the *highest published stable Release* (no new version; see <>). Fails if no Release qualifies. +|Released on merge at the latest `docs/v*` tag plus the bump the label selects: `docs/release` patch, `docs/release-minor` minor, `docs/release-major` major. +|Released on merge at the version in `docs/.release-version`, which the pull request commits; the file is then bumped forward. + +|*Manual run* (`workflow_dispatch`) +|Released at the version typed in the form. +|Released at the version typed in the form. The only way to cut the first release, or a bump other than patch after a Release event. +|Released at the version typed in the form; `docs/.release-version` is not bumped for a republish. +|=== + +In every case the tag is force-recreated if it already exists, and only `descriptor` runs the +descriptor bump and the git-flow sync. + === Under git-flow: the sync pull request This applies to the `descriptor` source only; the other sources have no bump to carry over diff --git a/docs/src/modules/main/pages/reference-cli.adoc b/docs/src/modules/main/pages/reference-cli.adoc index 0ed027e3..1063c9ee 100644 --- a/docs/src/modules/main/pages/reference-cli.adoc +++ b/docs/src/modules/main/pages/reference-cli.adoc @@ -231,7 +231,7 @@ Where the version comes from depends on `docouture.versionSource` in `docs/packa |Source |Version |`descriptor` |`--version` when given (the `workflow_dispatch` input), otherwise `docs/.release-version` -|`github-release` |The published release tag (`--release-tag`) minus `docouture.versionSourcePrefix`, when set. A merged `docs/release` pull request fails. +|`github-release` |The published release tag (`--release-tag`) minus `docouture.versionSourcePrefix`, when set. For a `docs/release` pull request, the highest stable SemVer among `--releases` (filtered by the prefix); it fails when none qualifies. |`tag-bump` |The highest `docs/v*` tag plus a bump chosen by `--labels`: `docs/release` patch, `docs/release-minor` minor, `docs/release-major` major (the highest wins). The first release needs `--version`. |=== @@ -255,6 +255,7 @@ instead, and the exit code stays 0. |`--release-tag ` |Tag of the published GitHub Release (`github-release`) |`--labels ` |Pull request labels, comma-separated (`tag-bump`) |`--tags ` |Existing tag names instead of listing git tags (`tag-bump`) +|`--releases ` |Tags of the published, non-draft, non-prerelease GitHub Releases (`github-release`, `docs/release` pull request); order does not matter. `--release-tag` wins when both are given |`--report` |Report a version error as output instead of failing |`--dir ` |Repository root (default: cwd, or its enclosing repo) |=== diff --git a/docs/src/modules/main/pages/release-notes/1-4-1.adoc b/docs/src/modules/main/pages/release-notes/1-4-1.adoc new file mode 100644 index 00000000..84bf40cf --- /dev/null +++ b/docs/src/modules/main/pages/release-notes/1-4-1.adoc @@ -0,0 +1,42 @@ += v1.4.1 + +[.lead] +A patch release. Under the `github-release` version source, a docs-only pull request +labelled `docs/release` can now republish the docs instead of failing after the merge. +Nothing changes for `descriptor` or `tag-bump`. The workflows call a new CLI flag, so update +the CLI first. Existing sites only get the new workflows by running `docouture upgrade`. + +== Do this + +. Update every `@inditextech/docouture-*` package, and the CLI if you install it, to + `1.4.1`, and install. The generated workflows run the CLI your project installed, and + they now pass `docouture release resolve --releases`, which older CLIs do not accept. +. Run `docouture upgrade`, review the diff, and commit `.github/workflows/`. See + xref:main:reference-cli.adoc[]. +. On a repository that publishes several packages, set `docouture.versionSourcePrefix` + (for example with `docouture version-source github-release --prefix docs-site@`), so the + right Release is picked. Without a prefix, the highest tag across all Releases wins. + +== What changed + +* *Changed: a docs-only `docs/release` pull request no longer fails under `github-release`.* + The workflow lists the repository's published, non-draft, non-prerelease GitHub Releases, + and `docouture release resolve` republishes the docs at the highest SemVer among them, + filtered by `docouture.versionSourcePrefix`. SemVer prereleases such as `1.5.0-rc.1` and + non-SemVer tags are ignored. The tag is force-recreated like any republish, with no + descriptor bump and no git-flow sync. With no usable Release, the merge fails with a + message naming the prefix and how many releases were considered. +* *New: `docouture release resolve --releases `.* The Release tags to choose from. Their + order does not matter, and `--release-tag` still takes precedence. +* *Changed: the release preview under `github-release`.* A `docs/release` pull request now + says merging republishes `docs/vX.Y.Z`, or warns that no Release was found. A pull request + that also has `release-type/*` keeps the "docs follow the code release" comment. The + preview job now runs your package manager's install under `github-release`, like + `tag-bump`. +* *New: a scenario-by-source table* of what each trigger releases, in + xref:main:guides-releasing-a-documentation.adoc#release-scenarios[]. + +== Limitations + +* A pull request labelled only `docs/release-minor` or `docs/release-major` has no bump to + apply under `github-release` and still fails; use `docs/release`. diff --git a/docs/src/modules/main/pages/release-notes/index.adoc b/docs/src/modules/main/pages/release-notes/index.adoc index 30dfb89b..80c2ac55 100644 --- a/docs/src/modules/main/pages/release-notes/index.adoc +++ b/docs/src/modules/main/pages/release-notes/index.adoc @@ -5,6 +5,7 @@ xref:main:changelog/index.adoc[Changelog], the unabridged commit-level record. == Versions +* xref:main:release-notes/1-4-1.adoc[v1.4.1] * xref:main:release-notes/1-4-0.adoc[v1.4.0] * xref:main:release-notes/1-3-2.adoc[v1.3.2] * xref:main:release-notes/1-3-1.adoc[v1.3.1] diff --git a/openspec/changes/github-release-docs-only-republish/.openspec.yaml b/openspec/changes/github-release-docs-only-republish/.openspec.yaml new file mode 100644 index 00000000..2a7773d6 --- /dev/null +++ b/openspec/changes/github-release-docs-only-republish/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-11 diff --git a/openspec/changes/github-release-docs-only-republish/design.md b/openspec/changes/github-release-docs-only-republish/design.md new file mode 100644 index 00000000..c28b83dc --- /dev/null +++ b/openspec/changes/github-release-docs-only-republish/design.md @@ -0,0 +1,46 @@ +# Design + +## Context + +`resolveGithubRelease` (`code/packages/cli/src/lib/release-resolve.ts`) is pure: the command gathers every input and the resolver decides. Today it returns an `unsupported` error for a `pull_request` event carrying `docs/release`, before it looks at any tag. `tag-bump` already shows the pattern for list inputs: the workflow fetches tags through `gh api` and passes them as `--tags`, and the resolver filters and orders them with `highestSemver` (`src/lib/semver.ts`). + +Both workflows exist twice: the template under `code/packages/cli/templates/workflows` (with `__DOCOUTURE_*__` placeholders) and the repo's own copy under `.github/workflows`, which differs only by those substitutions. The release workflow's job `if:` already keeps a PR with both `docs/release` and `release-type/*` on the Release-published path, so that path is unaffected. See proposal.md for motivation. + +## Goals / Non-Goals + +**Goals:** +- One tested implementation of "which Release is the latest" shared by the release and preview workflows. +- A docs-only `docs/release` PR under `github-release` republishes the highest stable Release's version without a manual dispatch. + +**Non-Goals:** +- Changing `descriptor` or `tag-bump` behavior. +- Letting a PR choose a version under `github-release`; the Release remains the source of truth. +- Reading GitHub Release notes or any other Release metadata. + +## Decisions + +**Filtering and ordering live in the CLI (`--releases`), not in shell.** The workflows pass raw tags from `gh api --paginate repos//releases --jq '.[] | select(.draft|not) | select(.prerelease|not) | .tag_name'`, joined with commas, and the resolver does prefix filtering, SemVer validation and ordering. Alternative: jq in each workflow, as the issue literally proposes. Rejected: it duplicates the logic in two workflows and is not unit-testable. The draft and GitHub-prerelease filter stays in the workflow query because that metadata is not in a tag name. + +**Highest SemVer, not newest.** `highestSemver` is reused. Alternative: first item by creation date. Rejected by the user: a backport released after `1.4.0` must not make a docs-only PR republish `1.3.9`. Input order is irrelevant, so the workflows need no sorting. + +**SemVer prereleases are excluded in the resolver.** A `1.5.0-rc.1` tag on a Release not flagged as GitHub prerelease would otherwise win and publish a release-candidate docs tag from a docs-only PR. "Latest Release" then means stable in both layers. Non-SemVer tags are skipped, not fatal: with a prefix they are most likely another package's release. + +**`--release-tag` stays and wins over `--releases`.** The Release-published event passes exactly the Release that just published; it must not be second-guessed by a list that might contain a higher unrelated version. Only when no release tag is given does the list apply. + +**Failure modes are explicit.** No usable Release names the prefix and the number of releases considered. A PR event with neither tag nor releases (an old workflow copy, or a caller that did not fetch) fails with a message about needing a published Release. Both keep the `unsupported`/`missing` error kinds so `--report` mode (preview) still reports instead of exiting non-zero. + +**Preview calls the resolver.** It currently hard-codes "no version" for `github-release`. It will fetch Releases with the same query and call `docouture release resolve --report`, as it already does for `tag-bump`, so the posted version cannot drift from what the merge does. `github-release` previews therefore need `npm install`, like `tag-bump`; `descriptor` stays install-free. The `release-type/*` branch of the comment is kept ahead of the new text. + +**Release workflow structure.** A step before "Resolve version" runs only for `pull_request` events when the source is `github-release` and writes the comma-joined tags to a step output; "Resolve version" passes it as `--releases`. The source and prefix are read by the CLI as today, so the workflow adds no new parsing of `docs/package.json`. + +## Risks / Trade-offs + +- [A repo with no prefix publishing several packages picks the highest tag across all of them] → Documented: declare `versionSourcePrefix`; the preview shows the version before merge. +- [`gh api --paginate` on a repo with very many Releases is slow] → Releases are returned newest first and a docs-only republish is rare; accepted, revisit only if it shows up. +- [Preview and release resolve at different times, so the version can differ] → The preview text already says the version can change if another Release publishes first. +- [Republishing overwrites the `docs/vX.Y.Z` tag] → That is the existing republish behavior for every source; this change adds no new force-push semantics. +- [Existing `github-release` sites with the old preview wording get a behavior change] → Release note and upgrade instructions; `docouture upgrade` refreshes the workflow templates. + +## Migration Plan + +Ship the CLI change and both templates together; sites pick them up with `docouture upgrade`. A site that does not upgrade keeps the old failing path (the old workflow never passes `--releases`, which now yields the clear "needs a published Release" message rather than the old wording). No rollback tooling needed: reverting the templates restores the previous behavior. diff --git a/openspec/changes/github-release-docs-only-republish/proposal.md b/openspec/changes/github-release-docs-only-republish/proposal.md new file mode 100644 index 00000000..ab3ec83d --- /dev/null +++ b/openspec/changes/github-release-docs-only-republish/proposal.md @@ -0,0 +1,36 @@ +## Why + +Under `docouture.versionSource: "github-release"`, a docs-only pull request cannot release the docs: a merged PR carrying `docs/release` makes `docouture release resolve` fail with `unsupported` after the merge, and the only way to publish a docs-only fix is a manual `workflow_dispatch` with an explicit version. A PR carries no version under this source, but the version can come from the highest published GitHub Release, which the resolver already knows how to parse (prefix strip, SemVer check). Follow-up to #299. Closes #313. + +## What Changes + +- `docouture release resolve` gains a `--releases ` input: the tags of the repository's published (non-draft, non-prerelease) GitHub Releases. Under `github-release`, a `pull_request` event carrying `docs/release` resolves to the highest SemVer among them instead of failing. The existing `--release-tag` (the Release that just published) keeps working and takes precedence when both are given. +- Selection: keep tags that start with `docouture.versionSourcePrefix` (all tags when no prefix is declared), strip the prefix, drop anything that is not SemVer or is a SemVer prerelease, pick the highest. Input order does not matter. +- With no usable tag, the command still fails, with a message that names the prefix and how many releases were considered. +- `docouture-release.yml` (repo copy and `code/packages/cli/templates/workflows` template): on a merged `docs/release` PR under `github-release`, list the repository's published Releases with `gh api` and pass the tags as `--releases`. The docs tag `docs/vX.Y.Z` is force-recreated as for any republish; no descriptor bump and no git-flow sync. +- `docouture-release-preview.yml`: under `github-release`, a `docs/release` PR says merging republishes docs `vX.Y.Z` (the highest Release). A PR without the label is no longer pointed at a failing path. If a `release-type/*` label is also present the existing "docs follow the code release" wording stays. +- Docs: a scenario-by-source matrix (code + docs PR, docs-only PR, `workflow_dispatch` against `descriptor` / `tag-bump` / `github-release`) in `guides-releasing-a-documentation.adoc`, mirrored in `skills/docouture-docs-versioning`, a release note, the `AGENTS.md` documentation-state ledger, and the `reference-cli.adoc` flag list. + +## Capabilities + +### New Capabilities + +None. + +### Modified Capabilities + +- `docs-release-resolve`: the `github-release resolver` requirement no longer fails for a `docs/release` pull request when releases are supplied, and gains the highest-SemVer selection rules and the `--releases` input; the `Resolve command interface` requirement lists the new input. +- `docs-release-preview`: the `Preview by version source` requirement states the republished version under `github-release` instead of "no version". + +## Impact + +- Code: `code/packages/cli/src/lib/release-resolve.ts`, `src/commands/release.ts` (flag parsing, usage text, report output), and their specs (`release.spec.ts` and the resolver tests). +- Workflows: `.github/workflows/docouture-release.yml` and `docouture-release-preview.yml`, plus the two templates in `code/packages/cli/templates/workflows`. The repo copy of the release workflow already differs from the template; the change keeps each consistent with its own file. +- Docs and skills: `docs/` pages named above, `skills/docouture-docs-versioning`, `AGENTS.md` ledger. +- Behavior change for existing `github-release` sites: a `docs/release` PR that used to fail now republishes. No breaking change for `descriptor` or `tag-bump`. +- Needs no new permissions: listing Releases works with the read-only `GITHUB_TOKEN` already available to both workflows. + +## Assumptions + +- SemVer-prerelease tags (for example `1.5.0-rc.1`) on a non-prerelease GitHub Release are excluded so "latest" means stable; to be confirmed during review. +- Tags that do not match the prefix, or are not SemVer, are skipped silently rather than failing. diff --git a/openspec/changes/github-release-docs-only-republish/specs/docs-release-preview/spec.md b/openspec/changes/github-release-docs-only-republish/specs/docs-release-preview/spec.md new file mode 100644 index 00000000..bfad021e --- /dev/null +++ b/openspec/changes/github-release-docs-only-republish/specs/docs-release-preview/spec.md @@ -0,0 +1,24 @@ +## MODIFIED Requirements + +### Requirement: Preview by version source +The preview SHALL read the version source from `docs/package.json`. Under `descriptor` it SHALL NOT install dependencies. Under `github-release`, for a pull request carrying `docs/release` and no `release-type/*` label, it SHALL list the repository's published Releases, compute the version with `docouture release resolve`, and state it as the version republished if the pull request merged now, noting the version can change if another Release publishes first; when no Release yields a version it SHALL say the merge will fail until a Release is published or the docs are released manually. Under `github-release`, for a pull request that also carries a `release-type/*` label without `skip-release`, it SHALL state that the docs are released when the code release publishes a GitHub Release, with no version. Under `tag-bump` it SHALL compute the version with `docouture release resolve` and state it as the version released if the pull request merged now, noting the version can change if another release lands first. + +#### Scenario: github-release +- **WHEN** a `github-release` pull request has `docs/release` and no `release-type/*` label, and the highest published Release is `1.4.0` +- **THEN** the comment says merging now republishes `docs/v1.4.0`, and that the version can change if another Release publishes first + +#### Scenario: github-release, no Release yet +- **WHEN** a `github-release` pull request has `docs/release` and the repository has no matching published Release +- **THEN** the comment says the merge will fail until a Release is published or the docs are released manually + +#### Scenario: github-release alongside a code release +- **WHEN** a `github-release` pull request has `docs/release` and a `release-type/*` label without `skip-release` +- **THEN** the comment says the docs follow the code release and names no version + +#### Scenario: tag-bump +- **WHEN** a `tag-bump` pull request has `docs/release-minor` and the latest tag is `docs/v1.2.3` +- **THEN** the comment says merging now releases `docs/v1.3.0`, and that the version can change if another release merges first + +#### Scenario: Descriptor stays cheap +- **WHEN** the version source is `descriptor` +- **THEN** the job runs no install step diff --git a/openspec/changes/github-release-docs-only-republish/specs/docs-release-resolve/spec.md b/openspec/changes/github-release-docs-only-republish/specs/docs-release-resolve/spec.md new file mode 100644 index 00000000..4553f181 --- /dev/null +++ b/openspec/changes/github-release-docs-only-republish/specs/docs-release-resolve/spec.md @@ -0,0 +1,59 @@ +## MODIFIED Requirements + +### Requirement: Resolve command interface +`docouture release resolve` SHALL accept the site mode (`versioned` or `standalone`), an optional explicit version, the repository root (default: cwd, or its enclosing repo), the event name, the published release tag, the tags of the repository's published GitHub Releases and the pull request labels, and SHALL print the resolved version, the release tag, the source the version came from and the active version source. It SHALL expose these as `key=value` lines suitable for appending to `$GITHUB_OUTPUT`. It SHALL read the active version source from `docs/package.json`, defaulting to `descriptor`, and SHALL print whether the descriptor bump and prerelease sync apply. + +#### Scenario: Versioned, version from the descriptor +- **WHEN** it runs in `versioned` mode with source `descriptor`, without an explicit version, and `docs/.release-version` contains `1.2.0` +- **THEN** it reports version `1.2.0`, tag `docs/v1.2.0` and source `docs/.release-version`, says the descriptor steps apply, and exits 0 + +#### Scenario: Standalone +- **WHEN** it runs in `standalone` mode +- **THEN** it reports version `stable` and tag `docs/stable` regardless of any file, version source or explicit version, says the descriptor steps do not apply, and exits 0 + +### Requirement: github-release resolver +Under `github-release` the version SHALL be the published release tag with `versionSourcePrefix` stripped when declared, and SHALL be validated as SemVer. A tag that does not start with the declared prefix SHALL fail. An explicit version SHALL still take precedence. When no release tag is given and the event is a pull request carrying `docs/release`, the version SHALL instead be the highest SemVer version among the supplied published GitHub Release tags, selected as follows: only tags that start with the declared prefix are considered (all tags when none is declared), the prefix is stripped, and tags whose remainder is not valid SemVer or is a SemVer prerelease are ignored. The selection SHALL NOT depend on the order of the supplied tags. When that selection yields no version the command SHALL fail with a message that names the declared prefix, if any, and the number of releases considered. A pull request carrying `docs/release` with neither a release tag nor any supplied releases SHALL fail with a message that says a published GitHub Release is needed to republish the docs, and names the configured source. A supplied release tag SHALL take precedence over the supplied releases. The descriptor steps SHALL NOT apply. + +#### Scenario: Plain tag +- **WHEN** the release tag is `1.4.0` and no prefix is declared +- **THEN** it reports version `1.4.0` and tag `docs/v1.4.0` + +#### Scenario: Prefixed tag +- **WHEN** the release tag is `docs-site@1.4.0` and the prefix is `docs-site@` +- **THEN** it reports version `1.4.0` + +#### Scenario: Wrong prefix +- **WHEN** the release tag is `other@1.4.0` and the prefix is `docs-site@` +- **THEN** it exits non-zero and says the tag does not start with the prefix + +#### Scenario: Docs-only pull request republishes the highest Release +- **WHEN** a pull request event has `docs/release`, the source is `github-release`, no release tag is given and the supplied releases are `1.3.9`, `1.4.0` and `1.2.0` +- **THEN** it reports version `1.4.0` and tag `docs/v1.4.0`, says the descriptor steps do not apply, and exits 0 + +#### Scenario: Highest SemVer, not newest +- **WHEN** the supplied releases are listed newest first as `1.3.9` then `1.4.0` +- **THEN** it reports version `1.4.0` + +#### Scenario: Prefix selects the package +- **WHEN** the prefix is `docs-site@` and the supplied releases are `api@9.0.1`, `docs-site@1.4.0` and `docs-site@1.3.9` +- **THEN** it reports version `1.4.0` + +#### Scenario: Prereleases and non-SemVer tags ignored +- **WHEN** the supplied releases are `1.5.0-rc.1`, `nightly` and `1.4.0` with no prefix declared +- **THEN** it reports version `1.4.0` + +#### Scenario: No matching Release +- **WHEN** the prefix is `docs-site@` and the supplied releases are only `api@9.0.1` +- **THEN** it exits non-zero and the message names `docs-site@` and that one release was considered + +#### Scenario: Release tag wins over supplied releases +- **WHEN** a release tag `1.5.0` and supplied releases including `1.9.0` are both given +- **THEN** it reports version `1.5.0` + +#### Scenario: Release label on a merged PR +- **WHEN** a pull request event has `docs/release`, the source is `github-release`, and neither a release tag nor any releases are given +- **THEN** it exits non-zero and says a published GitHub Release is needed to republish the docs + +#### Scenario: Explicit version +- **WHEN** an explicit version `2.0.0` is given on top of supplied releases +- **THEN** it reports version `2.0.0` diff --git a/openspec/changes/github-release-docs-only-republish/tasks.md b/openspec/changes/github-release-docs-only-republish/tasks.md new file mode 100644 index 00000000..39276828 --- /dev/null +++ b/openspec/changes/github-release-docs-only-republish/tasks.md @@ -0,0 +1,39 @@ +## 1. Resolver + +- [x] 1.1 In `code/packages/cli/src/lib/release-resolve.ts`, add `releases?: string[]` to `ResolveInput` and implement prefix filter, prefix strip, SemVer and non-prerelease filter and `highestSemver` selection for `github-release` +- [x] 1.2 Remove the unconditional `unsupported` early return for a `docs/release` PR; keep an explicit/release-tag precedence order (explicit, then release tag, then releases) +- [x] 1.3 Add the "no usable Release" error (names the prefix and the count considered) and the "needs a published Release" error for a PR with neither tag nor releases +- [x] 1.4 Extend `release-resolve.spec.ts` with one test per new scenario in `specs/docs-release-resolve/spec.md` + +## 2. CLI command + +- [x] 2.1 In `code/packages/cli/src/commands/release.ts`, parse `--releases` (comma or newline separated, like `--tags`), pass it to the resolver, and update the usage string +- [x] 2.2 Extend `release.spec.ts` for `--releases` end to end, including `--report` mode and `$GITHUB_OUTPUT`-style output + +## 3. Release workflow + +- [x] 3.1 In `code/packages/cli/templates/workflows/docouture-release.yml`, add a pull-request-only step that lists published, non-draft, non-prerelease Releases with `gh api --paginate` and outputs their tags; pass them as `--releases` in "Resolve version" +- [x] 3.2 Update the header comments of the template for the new `github-release` PR behavior +- [x] 3.3 Apply the same edit to `.github/workflows/docouture-release.yml` + +## 4. Preview workflow + +- [x] 4.1 In `code/packages/cli/templates/workflows/docouture-release-preview.yml`, make `github-release` fetch Releases, install the CLI and resolve with `--report`, like `tag-bump` +- [x] 4.2 Replace the "released with the code release, label does not release" comment with the republish-version comment, a no-Release-yet comment, and keep the `release-type/*` wording +- [x] 4.3 Fix the "add the label" suggestion path so it no longer leads into the failure under `github-release` +- [x] 4.4 Apply the same edits to `.github/workflows/docouture-release-preview.yml` +- [x] 4.5 Update workflow template tests, if any (grep `templates/workflows` in `src/**/*.spec.ts`) + +## 5. Docs and skills + +- [x] 5.1 Add the scenario-by-source matrix (code + docs PR, docs-only PR, `workflow_dispatch` for `descriptor`, `tag-bump`, `github-release`) to `docs/src/modules/main/pages/guides-releasing-a-documentation.adoc` +- [x] 5.2 Mirror it in `skills/docouture-docs-versioning` +- [x] 5.3 Document `--releases` in `docs/src/modules/main/pages/reference-cli.adoc` +- [x] 5.4 Add a release note under `docs/src/modules/main/pages/release-notes/` with its nav entry, per the 1.4.0 entry's pattern +- [x] 5.5 Update the `AGENTS.md` documentation-state ledger for every page touched + +## 6. Verify + +- [x] 6.1 Run the `cli` tests and lint through `pnpm nx` from `code/` +- [x] 6.2 Build the docs site and confirm no xref or nav errors +- [x] 6.3 Run `openspec validate github-release-docs-only-republish --strict` diff --git a/skills/docouture-docs-versioning/SKILL.md b/skills/docouture-docs-versioning/SKILL.md index 468f4e03..67e63bea 100644 --- a/skills/docouture-docs-versioning/SKILL.md +++ b/skills/docouture-docs-versioning/SKILL.md @@ -42,7 +42,8 @@ a release tag, and what the release workflow actually does). `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-minor` minor, `docs/release-major` major). Under `github-release`, a docs-only + `docs/release` PR republishes the highest published stable Release. 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`. diff --git a/skills/docouture-docs-versioning/reference/releasing.md b/skills/docouture-docs-versioning/reference/releasing.md index 76c8720b..90fad364 100644 --- a/skills/docouture-docs-versioning/reference/releasing.md +++ b/skills/docouture-docs-versioning/reference/releasing.md @@ -82,7 +82,7 @@ ordinary act, not something needing a separate flag. | 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 | +| `github-release` | tag of the published GitHub Release, minus `docouture.versionSourcePrefix` | a merged docs-only `docs/release` PR republishes the highest published stable Release (highest SemVer, filtered by the prefix, prereleases ignored; no Release means a clear failure); 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

] [--version ] @@ -96,11 +96,27 @@ optionally `docouture version-source`. `docouture doctor` shows the active sourc 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` +`github-release` shows the version a docs-only PR would republish (or says the docs follow the code release when the PR also has `release-type/*`), 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. +### Which trigger releases what + +"Code release" = the PR has `release-type/*` (no `skip-release`) and the code release publishes a GitHub Release. + +| scenario | `github-release` | `tag-bump` | `descriptor` (default) | +| --- | --- | --- | --- | +| PR with code + docs | not released on merge; on the Release, docs released at that Release's tag | not released on merge; on the Release, latest `docs/v*` tag + patch (a Release event has no labels) | not released on merge; on the Release, version in `docs/.release-version` | +| PR with only docs (`docs/release`) | released on merge: republishes the highest published stable Release; fails if none qualifies | released on merge: latest `docs/v*` + the label's bump (`docs/release` patch, `-minor`, `-major`) | released on merge at `docs/.release-version`, then the file is bumped forward | +| manual (`workflow_dispatch`) | version typed in the form | version typed in the form (the only way to cut the first release or a non-patch bump after a Release event) | version typed in the form; no bump on a republish | + +Under `github-release` the workflow lists the non-draft, non-prerelease Releases and +`docouture release resolve --releases` filters by `versionSourcePrefix` (all tags with no +prefix, so declare it when the repo publishes several packages), ignores non-SemVer and +SemVer-prerelease tags and picks the highest. The tag is force-recreated; no descriptor bump +or git-flow sync. + ## `docs/.release-version` after a release (`descriptor` only) Nothing clears it — it's bumped forward instead, except on a republish. On a genuine From 992f0779661f5a488dafe6bd73504a7f1eb252ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Thu, 12 Nov 2026 08:21:31 +0100 Subject: [PATCH 3/4] [tooling] Format CHANGELOG.md link references so Code / Verify passes The 1.4.0 release left blank lines between the link reference definitions, and prettier --check (Code / Verify) fails on them, on main as well. Whitespace only; no entry changed. Refs #313 --- code/CHANGELOG.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/code/CHANGELOG.md b/code/CHANGELOG.md index a1eb6c1c..64968db2 100644 --- a/code/CHANGELOG.md +++ b/code/CHANGELOG.md @@ -167,19 +167,11 @@ full convention, including why some issues produce no entry at all). Entries bel - [#33](https://github.com/InditexTech/docouture/pull/33) \[skills] Correct the iop-ds-components skill against the shipped package [Unreleased]: https://github.com/InditexTech/docouture/compare/1.4.0...HEAD - [1.4.0]: https://github.com/InditexTech/docouture/compare/1.3.2...1.4.0 - [1.3.2]: https://github.com/InditexTech/docouture/compare/1.3.1...1.3.2 - [1.3.1]: https://github.com/InditexTech/docouture/compare/1.3.0...1.3.1 - [1.3.0]: https://github.com/InditexTech/docouture/compare/1.2.0...1.3.0 - [1.2.0]: https://github.com/InditexTech/docouture/compare/1.1.1...1.2.0 - [1.1.1]: https://github.com/InditexTech/docouture/compare/1.1.0...1.1.1 - [1.1.0]: https://github.com/InditexTech/docouture/compare/1.0.0...1.1.0 - [1.0.0]: https://github.com/InditexTech/docouture/releases/tag/1.0.0 From 68e3ad1c90c8c6aa55e1eece94e1499189f68b38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Thu, 12 Nov 2026 08:25:24 +0100 Subject: [PATCH 4/4] [cli] github-release: clarify versionSourcePrefix applies to Release tags, not docs tags Refs #313 --- .../guides-releasing-a-documentation.adoc | 26 ++++++++++++++----- .../main/pages/release-notes/1-4-1.adoc | 10 ++++--- .../design.md | 2 +- .../proposal.md | 2 +- .../reference/releasing.md | 10 ++++--- 5 files changed, 34 insertions(+), 16 deletions(-) diff --git a/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc b/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc index abded03c..496e7bf5 100644 --- a/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc +++ b/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc @@ -70,7 +70,7 @@ pull request below). A versioned site can instead choose another source with |`docs/.release-version`, committed by the release pull request. The forward-bump and the git-flow sync described here apply only to this source. |`github-release` -|The tag of the published GitHub Release, minus the optional `docouture.versionSourcePrefix` (for example `docs-site@`). The docs follow the code release. A merged docs-only `docs/release` pull request republishes the docs at the *highest* published stable Release (see <>). +|The tag of the published GitHub Release, minus the optional `docouture.versionSourcePrefix` (for example `my-lib@`). The docs follow the code release. A merged docs-only `docs/release` pull request republishes the docs at the *highest* published stable Release (see <>). |`tag-bump` |The highest existing `docs/v*` tag plus a bump: `docs/release` bumps patch, `docs/release-minor` minor and `docs/release-major` major (the highest wins when several are present). The first release has no tag to bump from, so run `docouture-release` manually with an explicit version. @@ -106,17 +106,29 @@ instead: the *highest SemVer* version among them, not the newest one (a backport released after `1.4.0` does not make the docs go back to `1.3.9`). The workflow lists the non-draft, non-prerelease Releases and `docouture release resolve` then: -* keeps only tags that start with `docouture.versionSourcePrefix` (all tags when none is - set), so a repository that publishes several packages picks the right one; +* keeps only tags that start with `docouture.versionSourcePrefix` (with no prefix set, every + tag is tried as a version as it is), so a repository that publishes several packages picks + the right one; * strips the prefix and ignores anything that is not SemVer, or is a SemVer prerelease such as `1.5.0-rc.1`; * republishes `docs/v`. The tag is force-recreated like any republish, and there is no descriptor bump or git-flow sync. -Without a prefix, the highest tag across all of the repository's Releases wins, so declare -`docouture.versionSourcePrefix` on a repository that publishes more than one package. If no -Release matches, the merge fails with a message naming the prefix and how many releases were -considered; the preview comment warns about it first. +The prefix applies to the *Release* tags the version is read from, never to the `docs/v*` +tags this workflow creates. Docs tags are the output (`docs/v1.4.1`); Release tags are the +input (`1.4.1`, or `my-lib@1.4.1` when a repository releases several packages and prefixes +each package's tag). + +* *No prefix* (the default): only plain SemVer Release tags such as `1.4.1` are considered. + Prefixed tags like `my-lib@1.4.1` are not valid SemVer, so they are ignored. +* *With a prefix*, such as `my-lib@`: only that package's Releases are considered, and the + prefix is stripped before ordering. + +For example, the docouture repository publishes plain Releases (`1.4.0`, `1.3.2`, ...) and +sets no prefix, so a docs-only `docs/release` PR republishes `docs/v1.4.0`. + +If no Release matches, the merge fails with a message naming the prefix and how many +releases were considered; the preview comment warns about it first. [#release-scenarios] === Which trigger releases what diff --git a/docs/src/modules/main/pages/release-notes/1-4-1.adoc b/docs/src/modules/main/pages/release-notes/1-4-1.adoc index 84bf40cf..6bf5ec60 100644 --- a/docs/src/modules/main/pages/release-notes/1-4-1.adoc +++ b/docs/src/modules/main/pages/release-notes/1-4-1.adoc @@ -13,9 +13,13 @@ the CLI first. Existing sites only get the new workflows by running `docouture u they now pass `docouture release resolve --releases`, which older CLIs do not accept. . Run `docouture upgrade`, review the diff, and commit `.github/workflows/`. See xref:main:reference-cli.adoc[]. -. On a repository that publishes several packages, set `docouture.versionSourcePrefix` - (for example with `docouture version-source github-release --prefix docs-site@`), so the - right Release is picked. Without a prefix, the highest tag across all Releases wins. +. If your Release tags carry a prefix, for example `my-lib@1.4.1` in a repository that + publishes several packages, set `docouture.versionSourcePrefix` (for example with + `docouture version-source github-release --prefix my-lib@`) so the right Release is + picked. The prefix applies to the Release tags, not to the `docs/v*` tags the workflow + creates. Without a prefix, only plain SemVer Release tags such as `1.4.1` are considered, + and prefixed tags are ignored. A repository with plain tags, like this one, needs + nothing. == What changed diff --git a/openspec/changes/github-release-docs-only-republish/design.md b/openspec/changes/github-release-docs-only-republish/design.md index c28b83dc..5c93f1b1 100644 --- a/openspec/changes/github-release-docs-only-republish/design.md +++ b/openspec/changes/github-release-docs-only-republish/design.md @@ -35,7 +35,7 @@ Both workflows exist twice: the template under `code/packages/cli/templates/work ## Risks / Trade-offs -- [A repo with no prefix publishing several packages picks the highest tag across all of them] → Documented: declare `versionSourcePrefix`; the preview shows the version before merge. +- [A repo with prefixed Release tags and no `versionSourcePrefix` finds no Release, because prefixed tags are not SemVer and are skipped] → The merge fails with a message naming the prefix and the count, the preview warns first, and the docs say to declare the prefix. - [`gh api --paginate` on a repo with very many Releases is slow] → Releases are returned newest first and a docs-only republish is rare; accepted, revisit only if it shows up. - [Preview and release resolve at different times, so the version can differ] → The preview text already says the version can change if another Release publishes first. - [Republishing overwrites the `docs/vX.Y.Z` tag] → That is the existing republish behavior for every source; this change adds no new force-push semantics. diff --git a/openspec/changes/github-release-docs-only-republish/proposal.md b/openspec/changes/github-release-docs-only-republish/proposal.md index ab3ec83d..57ed17cf 100644 --- a/openspec/changes/github-release-docs-only-republish/proposal.md +++ b/openspec/changes/github-release-docs-only-republish/proposal.md @@ -5,7 +5,7 @@ Under `docouture.versionSource: "github-release"`, a docs-only pull request cann ## What Changes - `docouture release resolve` gains a `--releases ` input: the tags of the repository's published (non-draft, non-prerelease) GitHub Releases. Under `github-release`, a `pull_request` event carrying `docs/release` resolves to the highest SemVer among them instead of failing. The existing `--release-tag` (the Release that just published) keeps working and takes precedence when both are given. -- Selection: keep tags that start with `docouture.versionSourcePrefix` (all tags when no prefix is declared), strip the prefix, drop anything that is not SemVer or is a SemVer prerelease, pick the highest. Input order does not matter. +- Selection: keep tags that start with `docouture.versionSourcePrefix` (with no prefix declared every tag is tried as a version as it is, so only plain SemVer tags qualify), strip the prefix, drop anything that is not SemVer or is a SemVer prerelease, pick the highest. Input order does not matter. - With no usable tag, the command still fails, with a message that names the prefix and how many releases were considered. - `docouture-release.yml` (repo copy and `code/packages/cli/templates/workflows` template): on a merged `docs/release` PR under `github-release`, list the repository's published Releases with `gh api` and pass the tags as `--releases`. The docs tag `docs/vX.Y.Z` is force-recreated as for any republish; no descriptor bump and no git-flow sync. - `docouture-release-preview.yml`: under `github-release`, a `docs/release` PR says merging republishes docs `vX.Y.Z` (the highest Release). A PR without the label is no longer pointed at a failing path. If a `release-type/*` label is also present the existing "docs follow the code release" wording stays. diff --git a/skills/docouture-docs-versioning/reference/releasing.md b/skills/docouture-docs-versioning/reference/releasing.md index 90fad364..22ca05e9 100644 --- a/skills/docouture-docs-versioning/reference/releasing.md +++ b/skills/docouture-docs-versioning/reference/releasing.md @@ -112,10 +112,12 @@ bumps patch; use `workflow_dispatch` with an explicit version for a minor or maj | manual (`workflow_dispatch`) | version typed in the form | version typed in the form (the only way to cut the first release or a non-patch bump after a Release event) | version typed in the form; no bump on a republish | Under `github-release` the workflow lists the non-draft, non-prerelease Releases and -`docouture release resolve --releases` filters by `versionSourcePrefix` (all tags with no -prefix, so declare it when the repo publishes several packages), ignores non-SemVer and -SemVer-prerelease tags and picks the highest. The tag is force-recreated; no descriptor bump -or git-flow sync. +`docouture release resolve --releases` filters by `versionSourcePrefix`, ignores non-SemVer +and SemVer-prerelease tags and picks the highest. The prefix applies to the *Release* tags +(input, e.g. `my-lib@1.4.1`), never to the `docs/v*` tags the workflow creates (output). With +no prefix only plain SemVer Release tags (`1.4.1`) count and prefixed ones are ignored, so +declare the prefix when Release tags carry one; this repo's own Releases are plain (`1.4.0`), +so it sets none. The tag is force-recreated; no descriptor bump or git-flow sync. ## `docs/.release-version` after a release (`descriptor` only)