Docouture
prerelease Prerelease 1.3.2 Latest 1.3.1 1.3.0 1.2.1 1.2.0 1.1.2 1.1.1 1.1.0 1.0.0
↑↓ navigate · ↵ select · esc close
Docouture
Docouture
prerelease Prerelease 1.3.2 Latest 1.3.1 1.3.0 1.2.1 1.2.0 1.1.2 1.1.1 1.1.0 1.0.0

Branching model

docouture new --flow offers two shapes — decided at scaffold time, switchable later with docouture branch-model.

Trunk-based — the default

One long-lived branch (main by default) plays both roles: it’s the branch Antora tracks live as the prerelease version, and it’s the branch docouture-release.yml requires, checks out, and cuts tags from. There is no second code path anywhere for this — it’s the degenerate case where the two roles below happen to be the same branch.

Git-flow

Two independently-named branches, e.g. develop and main:

  • prerelease branch (develop) — what antora-playbook.yml’s `content.sources[].branches aggregates as the live prerelease version, and what docouture-publish-prerelease.yml watches (pushes to it republish automatically).

  • release branch (main) — what docouture-release.yml requires/checks out/pushes bump commits to, and what docouture-release-preview.yml watches (pull requests targeting it get a release preview comment).

Adopting git-flow maps directly onto the existing "merge a docs/release-labelled PR" release trigger — no event change, only the branch name it’s filtered against. Hotfix/release/* short-lived branches get no dedicated handling: they’re ordinary feature-branch-shaped PRs into develop/main from docouture’s perspective, already covered by the two roles above.

Which workflow watches which branch

Workflow Branch role it watches

docouture-pr-verify.yml

Neither — branch-agnostic, builds every PR’s own HEAD via antora-playbook.local.yml (but path-filtered: only fires when the PR touches docs/** or its own workflow file)

docouture-publish-prerelease.yml

prerelease branch (push trigger)

docouture-kroki-cache-warm.yml

both, unconditionally (push trigger — see below; also path-filtered to docs/** + its own workflow file)

docouture-release-preview.yml

release branch (pull_request trigger)

docouture-release.yml

release branch (pull_request:closed + workflow_dispatch); under git-flow its sync-prerelease job also opens a PR into the prerelease branch

docouture-publish.yml

Neither — never push-triggered, only workflow_call-chained from docouture-release.yml or manually dispatched

docouture-kroki-cache-warm.yml triggers on both branches unconditionally, not just one: GitHub’s cache-access rule only ever writes a trusted, cross-run cache entry from a push to the repository’s actual configured default branch — and there’s no reliable way to know at scaffold time which of the two a git-flow repo has set as that. Warming both means whichever one really is the default gets its cache entry written either way; the other branch’s push still produces a normal base-branch-scoped cache, so nothing is wasted. (On a trunk-based site this collapses to a single entry — both roles are the same branch.)

Both docouture-pr-verify.yml and docouture-kroki-cache-warm.yml are path-filtered to docs/** + their own workflow file — neither has anything to usefully check or warm a cache for from a change elsewhere in the repo. If docouture-pr-verify.yml is configured as a required status check in branch protection, confirm that setup tolerates a skipped run (GitHub’s "Do not require status checks on creation," or rulesets' own equivalent): a PR that never touches docs/ now means it never reports at all, rather than reporting green.

A release under git-flow, end to end

  1. Feature branch → develop: docouture-pr-verify.yml fires on the PR if it touches docs/** (it’s branch-agnostic, but path-filtered — see above). On merge, docouture-publish-prerelease.yml republishes the prerelease docs from develop.

  2. develop → main, labelled docs/release: docouture-pr-verify.yml fires under the same docs/** path filter, and docouture-release-preview.yml now fires too (targets main), posting a preview comment. On merge, docouture-release.yml cuts the release (checks out main, tags it, pushes the tag) and calls docouture-publish.yml to build and publish. A versioned release also bumps docs/.release-version on main; its sync-prerelease job then opens a pull request into develop carrying that bump (branch automated/sync-docs-release-<version>-to-develop) — merge it so develop doesn’t go stale. It runs before the publish, which doesn’t wait on its result: a failed sync turns the run red but the docs still publish.

  3. The merge to main is also an ordinary push — but docouture-publish-prerelease.yml does not fire a second time: its trigger is develop-only, so there’s no overlap with `docouture-release.yml’s own publish. (Under trunk-based, where both roles are the same branch, this same-push double-trigger risk is real, and `docouture-release.yml’s own header comment documents the mitigation.)

antora-playbook.yml’s `content.sources[] never lists the release branch

Only the prerelease branch appears under branches: — the release branch is never a live, content-tracked branch, only the checkout target docouture-release.yml cuts tags from. A tag is just a pointer to a commit; Antora’s tags: matcher doesn’t care which branch produced it. So docs/stable/docs/vX.Y.Z genuinely reflect whatever was on the release branch each time a release was cut, even though the release branch itself is never named in the playbook. See Versioning modes for what tags: is set to in each versioning mode.

Switching later: docouture branch-model

$ docouture branch-model git-flow --integration-branch develop
$ docouture branch-model trunk-based --branch main

Trunk-based → git-flow: the current single branch becomes the release branch by default (least disruption to anything already tagged off it) — --integration-branch (the new prerelease branch) is required, since there’s nothing on disk to infer that name from.

Git-flow → trunk-based: lossy — --branch is required and must match one of the two current branches exactly; a third, invented name is refused.

Either direction re-renders .github/workflows/ (the same machinery docouture upgrade uses) and patches antora-playbook.yml’s `content.sources[0].branches and docs/package.json’s `docouture.branching field. It does not rename actual git branches, touch branch-protection/ruleset rules, or change GitHub’s configured default branch — those stay manual steps, printed as a reminder after every real run.

The docouture block in docs/package.json declares the flow

"docouture": { "branching": "trunk-based" }
"docouture": { "branching": "git-flow", "prereleaseBranch": "develop" }

docouture-release.yml reads this block to know whether to open the prerelease sync pull request (see above) and which branch to target — the only place the workflow reads the flow from. Trunk-based declares branching only; git-flow also declares prereleaseBranch. docouture new, docouture branch-model and docouture upgrade keep it in step with antora-playbook.yml’s `content.sources[0].branches (what Antora actually builds from): upgrade writes or corrects it on a git-flow site, which also backfills sites scaffolded before the field existed. The release branch name is not stored — it’s the checkout ref: in docouture-release.yml.

docouture doctor compares the declaration against what the playbook and workflow actually say: a git-flow site without prereleaseBranch, or with a stale one, is reported with docouture upgrade as the fix. A hand-edited playbook leaves the declaration stale until upgrade (or branch-model) runs again.

Which one to pick

Trunk-based if one branch is genuinely enough — most sites. Git-flow if the repository this docs site lives alongside already reserves main for release/hotfix merges and uses develop as its integration branch — matching the docs site’s branching to the code’s avoids a confusing mismatch between the two.