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
41 changes: 34 additions & 7 deletions .github/workflows/docouture-release-preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -141,30 +141,33 @@ 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:
# `descriptor` reads the plain-text docs/.release-version this PR is
# 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
Expand All @@ -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)
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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}

Expand Down
36 changes: 33 additions & 3 deletions .github/workflows/docouture-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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")
Expand All @@ -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"
Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
8 changes: 0 additions & 8 deletions code/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
41 changes: 40 additions & 1 deletion code/packages/cli/src/commands/release.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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')
Expand Down
3 changes: 2 additions & 1 deletion code/packages/cli/src/commands/release.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import {
} from '../lib/release-resolve.js'

const USAGE =
'usage: docouture release resolve --mode <versioned|standalone> [--version <v>] [--event <name>] [--release-tag <tag>] [--labels <a,b>] [--tags <a,b>] [--report] [--dir <path>]'
'usage: docouture release resolve --mode <versioned|standalone> [--version <v>] [--event <name>] [--release-tag <tag>] [--labels <a,b>] [--tags <a,b>] [--releases <a,b>] [--report] [--dir <path>]'

type Flags = Record<string, string | boolean>

Expand Down Expand Up @@ -114,6 +114,7 @@ async function runResolve(argv: string[]): Promise<number> {
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),
Expand Down
53 changes: 52 additions & 1 deletion code/packages/cli/src/lib/release-resolve.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down
Loading
Loading