From 6dccba710b9b402b93f79bf2eda068bf56a111df Mon Sep 17 00:00:00 2001 From: Patrick Kollitsch <83281+davidsneighbour@users.noreply.github.com> Date: Sun, 22 Nov 2026 03:33:11 +0000 Subject: [PATCH] chore(skills): add draft release workflow (#1139) --- .agents/skills/release/references/v2.21-release-record.md | 87 +++++++++++++++++++++ .agents/skills/release/references/backlog.md | 54 +++++++++++++ .agents/skills/release/SKILL.md | 45 +++++++++++ 3 files changed, 186 insertions(+), 0 deletions(-) diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md new file mode 100644 index 0000000..fefe097 --- /dev/null +++ b/.agents/skills/release/SKILL.md @@ -0,0 +1,45 @@ +--- +name: release +description: "Draft workflow for checking an Ananke release candidate, preparing its notes, and, when explicitly requested, publishing the theme and documentation." +metadata: + status: draft +--- + +# Release preparation + +Draft for maintainer review. This skill describes two steps; it does not install an automated release runner. Do not commit this draft until the maintainer asks. + +Use `check [version]` for readiness and note preparation. Use `release <version>` for publication. If the request only says "prepare" or "check", finish step 1 without starting step 2. An explicit release request authorises its stated publication scope; do not ask again for actions already authorised. + +Resolve paths from the Ananke root. The documentation checkout is normally its sibling `../documentation`; verify its identity. Read each repository's applicable instructions and the [development reference](../../references/development.md). Read [the backlog](references/backlog.md) before planning checks. Consult [the v2.21 record](references/v2.21-release-record.md) for historical evidence or a matching roadblock, not as a script to replay. + +## Step 1: check + +1. **Establish the candidate.** Inspect both working trees and current local and remote `main` and `development` refs. Preserve unrelated work. Identify the previous stable theme tag and the requested version; do not derive a version from a note's filename. Record the exact candidate SHAs and the full changes since the previous release, including changes already on development before the latest feature PR. +2. **Run relevant checks.** Run theme quickstart, feature coverage, and the browser tests affected by the release. For navigation and layout changes, cover mobile and desktop sizes, keyboard access, focus, no-JavaScript output, and overflow. Test the declared minimum Hugo version and a verified current release; record the exact binaries used. Check Hugo Module and Git submodule consumers when installation behaviour changes. Do not install tools globally without need. +3. **Keep validation scoped.** Exclude `scratch/` from all linting, compilation, packaging, and error checks. Inspect command scope before invoking aggregate commands such as `npm run check`: the current TypeScript include is broad. Use an equivalent scoped check when necessary, and say which full check was not run. Record baseline failures separately from regressions; do not label the candidate fully passing when a required gate fails. Obtain a maintainer decision on unresolved release blockers unless that decision is already explicit. +4. **Check the documentation.** Match documented parameters, defaults, hooks, precedence, mobile behaviour, image sources, requirements, and upgrade advice to the implementation. Verify renamed-page aliases, internal links, search, option references, and tables on relevant screen sizes. Use local replacement or remote preview selection for unreleased changes; a successful preview does not prove a production build uses that revision. +5. **Prepare the release text.** Use a supplied note path or a specifically named release draft. If no draft exists, create one within the authorised scope. Read scratch notes only when explicitly included in the request, and never lint or run error checks on scratch. Update the prose to cover the complete release range, with a linked contents list, the main user-facing changes first, documentation and upgrade guidance, and contributor/tooling changes last. Use final production documentation URLs; distinguish links that will become live after publication. State only requirements and compatibility changes supported by this candidate. Do not copy historical SASS migration or Hugo-version boilerplate from the old release-notes skill. +6. **Verify the proposed version.** Inspect `.release-it.ts`, its installed configuration package, the previous tag, and Conventional Commits. Run the actual release script with `--dry-run --ci --no-github.comments.submit`. Stable releases require a branch named `main`; if the candidate is still on development, use an isolated disposable clone with local main at that candidate. Do not promote the live branches merely to make a check work. Stop and explain any proposal different from the requested version. A major proposal needs a separate maintainer decision because the module path is `github.com/gohugo-ananke/ananke/v2`; never silently force or publish a major. +7. **Report readiness.** Record the note path, candidate refs, proposed version, tool versions, checks, baseline exceptions, required documentation updates, and outstanding decisions. A check result is evidence for this candidate only. Prepare the concrete release plan before asking for any missing approval. Do not commit, push, tag, merge PRs, alter repository settings, or deploy in check mode. + +Useful existing checks include `npm test`, `npm run test:coverage-gate`, and `npm run test:e2e` in the theme, and `npm run test:build` in documentation. Read the current scripts and scoped instructions before choosing the exact commands. + +## Step 2: release + +Run this step only when the user requests publication and the target version and notes are settled. Check mode alone does not authorise it. + +1. **Reconfirm the candidate and scope.** Recheck refs, working trees, source notes, required CI, and unresolved blockers against the readiness record. Rerun checks affected by intervening changes. Confirm whether the request includes documentation publication. Retain both `development` branches throughout. +2. **Promote the theme.** Rebase development onto main as needed, then use a development-to-main PR with a rebase merge. No squash or merge commit for promotion. Verify the resulting tree against the reviewed candidate. Check source-branch auto-deletion before merging; ensure development cannot be deleted. If a temporary setting change is needed within the authorised scope, record its original value and restore it even if a later step fails. +3. **Run the release script on main.** Repeat the dry run on the actual promoted main. Stop if the proposed version changes. Inspect current credentials through the configured token variable without printing or persisting secrets. Use `npm run release -- "$release_version" --ci --no-github.comments.submit` with the settled semantic version and the approved text supplied through the supported `github.releaseNotes` option, using safe command quoting. The script currently updates version/changelog files, commits, tags, pushes, creates the GitHub release, and creates its linked discussion; npm package publication is disabled. Do not replace this process with an ad hoc tag. Do not post issue/PR comments or social announcements unless those are separately authorised. +4. **Verify publication before continuing.** Confirm the exact stable tag, its target commit, remote main, package version, release body, and published rather than draft/prerelease status. If a command fails after changing remote state, inspect what already exists before retrying. Do not recreate or move a published tag. If the text needs correction, update both the release and its copied discussion body, without changing released code. +5. **Resolve and pin the documentation dependency.** Confirm Go can resolve the published `/v2` module tag. Update documentation's checked-in `go.mod` and `go.sum` to that tag, without retaining a feature revision or local replacement. On its reviewed development branch, run `npm run build -- --expect-theme-version "v$release_version"` and relevant checks. Record the actual resolved module and Hugo version. If the resolver returns the old stable tag, stop this phase and retry after availability changes; never publish the old result as the new release. +6. **Promote and deploy documentation.** Only after the theme release is available and the guarded build passes, promote documentation development to main through a rebase PR. Verify tree equality and retain development. Observe the existing main-triggered Netlify production and GitHub Pages deployments. Do not issue a duplicate manual deployment when the automatic one succeeds. If a manual production deploy is required and authorised, use the existing linked site and `npm run deploy:production -- --expect-theme-version "v$release_version"` from main. +7. **Verify the live result and retain the branches.** Confirm deployment state, published source commit, canonical site URL, release links, old URL redirects, search, mobile navigation, and responsive tables as applicable. Keep preview, branch-deploy, and production evidence distinct. Rebase retained development branches onto their released main histories; verify trees and use an exact old-SHA lease for any required shared-branch rewrite. Never delete development. +8. **Close the record.** Report the actual version, release/discussion URLs, production URL, commit/deploy identifiers, branch state, checks, and limitations. Save commands, roadblocks, remedies, and new improvement candidates in the release record and backlog. A source merge, local build, and live deployment are separate outcomes; claim only what was observed. + +For restricted environments, prefer writable task-specific caches and process-local transport settings. Preserve checksum verification and global credentials. The [v2.21 record](references/v2.21-release-record.md) explains why a fresh module cache, writable GOPATH, and writable XDG cache can each matter. + +## Draft follow-up + +Maintain [the backlog](references/backlog.md). It distinguishes implemented release capabilities from manual procedure, incomplete safeguards, and future work. New scripts, workflow changes, or fixes require their own implementation and meaningful validation; this draft does not imply that they exist. diff --git a/.agents/skills/release/references/backlog.md b/.agents/skills/release/references/backlog.md new file mode 100644 index 0000000..8709299 --- /dev/null +++ b/.agents/skills/release/references/backlog.md @@ -0,0 +1,54 @@ +# Release preparation backlog + +Draft reviewed against the current main branches on 20 November 2026: Ananke `8c18c8412c9e`, documentation `ce1d18c0b678`. This list records remaining work; it does not authorise implementing it during a release check. + +## Release tooling and automation to add + +* [ ] Add a machine-readable readiness record containing candidate refs, proposed version, note path, check results, and unresolved blockers. Refuse to use a stale record after candidate changes. +* [ ] Add an explicit requested-version and allowed-major guard around the real release script. The current Conventional Commit configuration can recommend a major release; dry-run review and human decisions are still manual. +* [ ] Protect long-lived development branches from automatic source deletion. Ananke currently enables repository-wide auto-deletion; v2.21 temporarily disabled and restored it. Prefer durable branch retention over a broad setting toggle. +* [ ] Automate the stable theme release to documentation hand-off: wait for module availability, pass the expected tag, update checked-in pins, run the guarded build, and only then promote documentation main. +* [ ] Pass the expected theme version into hosted production builds, not only the maintainer's local pre-publication check. The command-line guard exists; automatic pipelines do not yet receive the release's expected tag. +* [ ] Add release-record capture for commands, failures, versions, remote refs, deployment identities, and live checks. Keep temporary paths as observations rather than future defaults. +* [ ] Decide the maintained Hugo compatibility range and test it in the release gate. v2.21 used theme builds with 0.160.0, 0.161.1, and 0.170.1, and documentation with 0.170.1; this is historical evidence, not a permanent latest-version policy. +* [ ] Generalise documentation's test-release publication guide and reconcile its contributor instructions with the two retained branches. `content/help/development.md` records the correct publication order; `CONTRIBUTING.md` still describes main as its only long-lived branch. +* [ ] Make release-note preparation use candidate evidence and reusable editorial guidance. Remove or supersede the mandatory historical SASS breaking-change and fixed Hugo requirement in `ananke-release-notes/SKILL.md`; do not silently reuse them. +* [ ] Add a supported notes-file interface for release creation, with safe handling of file paths, and a synchronised correction path for the release and its copied discussion. v2.21 used release-it's command-valued `github.releaseNotes` option. +* [ ] Define recovery after partial publication: inspect tag/release state, avoid duplicate side effects, and resume documentation publication without recreating the theme tag. +* [ ] Avoid duplicate, empty integration records when a local squash has already been pushed before its PR is completed. v2.21 retained empty integration commits after promotion; their trees were verified. + +## Existing validation work still open + +* [ ] Theme: add a meaningful `edit-page` shortcode test and register it in `tests/catalog.yaml`. The current coverage gate was rerun for this review and still fails for that missing entry. +* [ ] Theme: scope TypeScript and aggregate checks so they cannot traverse `scratch/`. `tsconfig.json` still includes `**/*.ts` without a project-level scratch exclusion. Do not rerun the old scratch-directory compilation errors as a check. +* [ ] Documentation: resolve the previously reported LinkedIn recipe ordered-list lint issue. This is a baseline issue, not a v2.21 regression; rerun the focused Markdown check when taking it on. +* [ ] Isolate shared development launcher tests from an active preview on port 1313. v2.21 tested temporary copies with a free port; the maintained launcher-test solution remains to be added. +* [ ] Review the existing dependency advisory notices separately. The release push reported advisories, but neither their current severity nor remedies are established by this draft. + +## Planned compatibility work + +* [ ] At a separately approved v3 transition, handle [Ananke issue #1120](https://github.com/gohugo-ananke/ananke/issues/1120): remove override detection/markers, decide the internal role of the legacy header partials, and document the migration. Do not perform that removal in the current v2 release line or infer permission for a major release. + +## Implemented capabilities to keep + +* Header components, before/after hooks, configurable groups, class precedence, submenu modes, responsive mobile lists, and targeted override warnings are implemented and documented. +* The old unreleased `navigation-start` and `navigation-end` proposal was superseded by component hooks; adding those old names is not pending work. +* Documentation uses the theme navigation and a search component, with aliases for moved pages, responsive tables, and compact option references. +* Local development explicitly selects the sibling theme through an environment replacement. Production and remote previews resolve their own revisions in temporary source trees. +* Production resolves a stable release, prints the selected version, preserves source dependency files, supports `--expect-theme-version`, and builds Pagefind. Draft and production deployments are distinct. +* The stable theme script requires main and supports dry runs. Existing automation deploys documentation main to Netlify and GitHub Pages. + +## Scratch-note disposition + +All six reviewed notes can be removed after this draft and its historical reference are saved: + +| Source note | Disposition and retained evidence | +| --- | --- | +| `scratch/header-rework/result-001.md` | Components and layout are on main and documented in the header guide. The test catalogue and check-scoping gaps are retained above. | +| `scratch/header-rework/result-002.md` | Branch integration and targeted deprecation are complete. The original hook/mobile proposals were superseded. Future removal remains in issue #1120 and the checklist above. | +| `scratch/release-notes/release-notes-1.21.md` | Published as [v2.21.0 release notes](https://github.com/gohugo-ananke/ananke/releases/tag/v2.21.0) and [discussion #1124](https://github.com/orgs/gohugo-ananke/discussions/1124). | +| `scratch/2026-11-19-multilevel-menu-docs.md` | Menu hierarchy, controls, labels, keyboard behaviour, current states, no-JavaScript behaviour, and upgrade advice are documented. Later four-mode/mobile requirements supersede the early proposal. | +| `scratch/2026-11-19-navigation-redesign-docs.md` | Theme navigation, the search hook, class scaffold, and responsive layout are integrated and documented. Component hooks supersede the proposed start/end hooks. | +| `scratch/2026-11-20-v2.21-release-run.md` | Historical record preserved in [the v2.21 release reference](v2.21-release-record.md); reusable steps are in SKILL.md, with pending automation above. | + +Current source guides are `documentation/content/configuration/menus.md`, `documentation/content/customisation/header.md`, `documentation/content/customisation/hooks-and-filters/all.md`, and `documentation/content/help/development.md`. Refer to the exact main revisions above when comparing this audit with later work. diff --git a/.agents/skills/release/references/v2.21-release-record.md b/.agents/skills/release/references/v2.21-release-record.md new file mode 100644 index 0000000..f5ecee0 --- /dev/null +++ b/.agents/skills/release/references/v2.21-release-record.md @@ -0,0 +1,87 @@ +# Ananke v2.21.0 release run + +Historical reference copied during scratch cleanup on 20 November 2026. This preserves the observed v2.21 run, including temporary paths, intermediate states, and remedies. It is not a reusable command sequence. Use SKILL.md for the draft workflow and backlog.md for outstanding work. The final outcome below supersedes intermediate instructions to verify a result. + +Started: 2026-11-20, Asia/Bangkok. Source repositories: gohugo-ananke/ananke and gohugo-ananke/documentation. User authorises linear promotion, the v2.21 release, publishing supplied release text, and production documentation deployment. Do not publish a major version; stop to discuss any different proposal. + +## Starting evidence + +* Theme development: f698c7319d5de8d74eefe0c199dc9e219a08adb8. Main: 28aa100be34116d15a360d7c6c0a17638f10775a (v2.20.0). +* Documentation development: 83658950060129d91e3ff1db658b24f5471aaa82. Main: 7e60304f92ff82b83306492581c1e20b4de2ae5a. +* Both working trees clean. Existing promotion PR searches returned none. Both repositories allow rebase merging. Main branches reported unprotected. +* Theme script: npm run release, release-it 21.1.2, @dnbhq/release-config 2.0.1. Stable command requires main; npm publication disabled. It updates package/changelog, commits, tags, pushes, creates a GitHub release and discussion, and submits configured release comments. +* Documentation production build resolves latest stable Go module in a temporary source tree, preserves source dependency files, and supports --expect-theme-version. Main pushes trigger Netlify production and GitHub Pages. +* Local Node v26.13.1; system Hugo v0.170.0; verified Hugo v0.170.1 binary already available under /tmp/ananke-hugo-latest. + +## Plan and constraints + +1. Refresh remote refs, rebase each development branch onto its main, and preserve commit history. +2. Promote theme through a development-to-main PR using rebase merge. Verify file tree and no merge commits. +3. Run the actual release script in dry-run mode first. Confirm it proposes 2.21.0. Publish only that minor version, using the supplied notes. +4. Resolve v2.21.0 through the Go module path and build documentation with an explicit expected-version guard before promoting documentation main. +5. Promote documentation through a rebase PR; verify live production deployment and the actual resolved theme, not only build success. +6. Save a final isolated scratch record with commands, identifiers, failures, remedies, and automation candidates. + +## Known operational limits + +* Git SSH fails due to permissions on /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf. Prior fetches succeeded over HTTPS. Use command-scoped transport settings; do not change global SSH configuration or expose tokens. +* GitHub connector reads work but PR writes returned integration 403 earlier. Authenticated gh CLI works; use it for authorised writes. +* Do not deploy documentation before the stable theme tag is available. Merely merging main does not publish a Go version. +* Existing full coverage catalogue issue for edit-page and LinkedIn recipe Markdown numbering are baseline issues, not regressions from this release. Focused checks and 94 browser tests passed on the integrated tree. +* Scratch notes are never committed or linted. The user's supplied release text remains the publication source; do not apply historical SASS migration boilerplate from the old release-notes skill to this release. + +## Execution record + +* Ref refresh over HTTPS succeeded. Both requested development-on-main rebases were already up to date; neither changed commits or files. +* Created theme promotion PR #1123, development to main, explicitly requiring a rebase merge and retaining development. +* User repeated the requirement to retain both development branches. Ananke has delete_branch_on_merge=true; documentation has false. Temporarily disable Ananke automatic deletion around the promotion, then restore it and verify development still exists. +* Release-specific token is not present in the inherited environment. Use the existing authenticated gh token only within the release child process; do not print or persist credentials. A temporary runner also applies HTTPS rewriting and gh credential helper only to that process. +* Netlify CLI initially failed with EROFS while updating ~/.config/netlify/config.json. The approved unsandboxed status check succeeded: existing login, team ananke, linked site c8355bd4-cc5a-4651-9438-9d0f37d88ccc, URL [Ananke documentation](https://ananke-documentation.netlify.app). CLI version 27.17.0. No new project or login needed. +* Theme promotion PR #1123 passed its quickstart and branch-policy checks, then merged using GitHub rebase at 804d93a7a98f2fead5e905801c6fc1f42596a27c. Automatic deletion was disabled before merging, development existence was verified, and the setting was restored to true afterwards. +* Main's tree exactly matched the tested development tree. No merge commits occurred in v2.20.0..main. Local main was fast-forwarded to the promotion result. +* Actual release script dry run succeeded and proposed 2.20.0 -> 2.21.0 automatically. No major proposal or forced change to the configured bump rules was needed. Log: /tmp/ananke-v2.21-dry-run.log. +* Publication command: node /tmp/ananke-release-runner.mjs 2.21.0 --ci --no-github.comments.submit --github.releaseNotes='cat scratch/release-notes/release-notes-1.21.md'. The wrapper invokes npm run release with a process-local HTTPS transport and authenticated token. Automatic comments on historical issues/PRs are disabled; the supplied notes are used at release creation. +* Release succeeded in 10 seconds. Release commit 8c18c8412c9edc79d24e982c43a3ef58867a44af; annotated tag object 5fde6c7bdff17ba6e380386ebf6ad33e58ccc0dc; published release [v2.21.0 release](https://github.com/gohugo-ananke/ananke/releases/tag/v2.21.0) at 2026-11-20T10:49:54Z; discussion [release discussion](https://github.com/orgs/gohugo-ananke/discussions/1124). Verified stable, published, not a draft/prerelease. Updated CHANGELOG.md, package.json, and package-lock.json only. +* Go resolves v2.21.0 to the release commit. The first go-list command warned that its default home cache was read-only, although version resolution succeeded. Use a task-specific writable module cache for later commands. +* First documentation dependency update failed because inherited Git HTTPS-to-SSH rewriting sent Go through the broken SSH configuration. Retry with GIT_CONFIG_GLOBAL=/dev/null, explicit public Go proxy/checksum settings, no inherited Hugo replacements, and a writable Hugo cache under /tmp. These overrides are process-local; do not change user configuration. +* Reusing the first failed Hugo module cache retained a VCS origin configured for SSH, even after disabling global Git settings. A fresh cache avoids that persisted transport. A fresh Go module cache alone was insufficient: checksum database state uses GOPATH/pkg/sumdb, so GOPATH also needs a writable /tmp path. Checksum verification stayed enabled. +* Successfully pinned documentation to v2.21.0 with process-local public proxy/checksum settings, GIT_CONFIG_GLOBAL=/dev/null, GOPATH=/tmp/ananke-v2.21-gopath, and GOMODCACHE=/tmp/ananke-v2.21-clean-go-cache. Committed go.mod/go.sum as bf2db208ee07168980672aed944f5aeeb38ddc08 and pushed development. +* Production build passed with --expect-theme-version v2.21.0, Hugo 0.170.1, writable GOPATH/cache, and destination /tmp/ananke-v2.21-production. It resolved latest to v2.21.0, generated 80 HTML pages, and indexed 53 pages. Release documentation destinations and anchors exist. Eight build-selection tests passed. Logs: /tmp/ananke-v2.21-docs-build.log and /tmp/ananke-v2.21-docs-tests.log. +* Created documentation promotion PR #77; Netlify deploy preview passed. Ananke development was rebased onto the released main history, skipping already-applied patches and retaining its empty integration record as df07ae28ed2b0ba31d1705239192229d94cda9fe. Its tree matches main. Synchronise with an exact old-SHA lease; never delete development. +* Documentation #77 merged by rebase at 0d3f7862487d32e2c41ab9fbb4aaaae346fe6035 on 2026-11-20T10:52:34Z. Local main was fast-forwarded and matched the tested development tree, with no merge commits in the promoted range. +* Netlify's existing main-branch integration automatically published production deploy 6b002674297f644abf5d1d54 (build 6b002674297f644abf5d1d52), state ready, main commit 0d3f7862487d32e2c41ab9fbb4aaaae346fe6035, published 2026-11-20T10:52:49.466Z. API confirms production branch main, successful build, and no error. No redundant manual deployment was needed. +* GitHub Pages workflow 44722892431 passed both build and deploy; logs explicitly show Hugo 0.170.1 and resolved theme v2.21.0. Public Pages URL: [GitHub Pages documentation](https://gohugo-ananke.github.io/documentation/). Reading logs first failed because ~/.cache/gh was read-only; XDG_CACHE_HOME=/tmp/ananke-v2.21-xdg-cache fixed log retrieval. +* Rebased and retained documentation development as fb36344c8426af9b568e1bf6cd2e8dd487b51167, preserving its empty integration record, with the same tree as main. Pushed both development branches using exact expected old-SHA leases. Both local checkouts are on main and clean; development branches exist remotely. +* Live Netlify browser checks passed at 375, 768, and 1280 pixels: HTTP 200, no page overflow, responsive option references. Mobile hamburger opens six visible indented child lists with zero visible submenu buttons. Migration, responsive-image, and publication-order guides return 200. The old installation URL resolves to the new Hugo Module guide. +* Final factual review caught an error in the prepared release draft: ananke.header.navigation.submenu_mode should be ananke.navigation.submenu_mode. The theme resolver and live documentation were already correct. Correct the source draft and published release notes without changing the release tag or code; record the post-publication correction. +* Corrected the setting name in the local source draft, published GitHub release, and the release-linked discussion #1124 (GitHub had copied the original notes there). The release remains stable v2.21.0, not a draft/prerelease, with its original tag and code. +* Final remote refs verified: theme main 8c18c8412c9edc79d24e982c43a3ef58867a44af, theme development df07ae28ed2b0ba31d1705239192229d94cda9fe, documentation main 0d3f7862487d32e2c41ab9fbb4aaaae346fe6035, documentation development fb36344c8426af9b568e1bf6cd2e8dd487b51167. Main is an ancestor of development in both repositories. No merge commits were introduced. Ananke automatic source-branch deletion restored to its original true value; documentation remains false. +* Live search successfully returned the header guide and related sections. GitHub Pages menu guide returned HTTP 200. Search automation initially used the wrong input type and then a non-unique placeholder selector; selecting the combobox by its accessible name fixed the checks. These were test-selector mistakes, not product failures. +* Live search exposed three remaining development-only descriptions of responsive header images in content/content/images.md and content/customisation/hero-section.md. Changed them to availability from v2.21.0, passed focused Markdown linting, and committed the release wording as 0bb3fe9c0484 on documentation development for rebase promotion. No theme code or release tag change needed. +* Documentation follow-up PR #78 passed its deploy preview and merged with rebase at ce1d18c0b678709166f56c86d714e1df1753ab02 on 2026-11-20T11:00:56Z. Retained development was rebased again, tree-verified, and pushed with the exact old-SHA lease; final tip a0eb85a137d1d9358ce6c17f3e2d49e25ca6c322. Both local checkouts remain on main. +* Final Netlify production deploy 6b00286ac3f0b648b94b88f0 (build 6b00286ac3f0b648b94b88ee) is ready, from main commit ce1d18c0b678709166f56c86d714e1df1753ab02, published 2026-11-20T11:01:09.327Z. Browser HTTP 200 confirms the released wording and absence of the old development-only sentence. +* Follow-up GitHub Pages run: [GitHub Pages workflow run](https://github.com/gohugo-ananke/documentation/actions/runs/44724044831). Verify its terminal result before closing the task. + +## Guidance and automation candidates + +* Separate theme promotion, theme publication, module availability, documentation promotion, and live verification into explicit phases. Publication order prevented an old-stable documentation build. +* Always dry-run the actual release configuration, inspect its proposed version, and gate the authorised minor version before any tag/push. A breaking Conventional Commit can propose a major version; stop for the maintainer rather than forcing it silently. The Go module remains /v2. +* Protect long-lived development branches from source-branch auto-deletion. A future promotion workflow should enforce this without temporarily changing the repository-wide setting. +* Use a task-specific writable GOPATH, module cache, Hugo cache, and XDG cache in restricted environments. Fresh Go VCS caches matter after transport failures. Preserve checksum verification and avoid global credential/SSH changes. +* Explicitly update checked-in documentation pins after publication, even when production resolves latest, so ordinary Hugo builds also use the released theme. +* Pass the exact stable tag through a release-to-documentation workflow and use --expect-theme-version. Verify the selected version in CI logs and the published commit/deploy ID separately. +* Use main-triggered deployment once; observe its result instead of running a duplicate manual production deploy. Keep deploy previews, branch deployments, Netlify production, and GitHub Pages evidence distinct. +* Rebase promotion changes commit IDs. Verify resulting trees, retain development, rebase it onto released main, and push shared refs only with an exact-SHA lease. Existing empty integration commits survived the final rebases; they are harmless but make branch history less clear. +* Confirm documented parameter paths against the implementation before publication. If release text is corrected later, update both the GitHub release and its copied discussion body. +* Update the release-notes skill before reuse: its historical mandatory SASS breaking-change and Hugo requirement boilerplate does not describe this release. Do not insert it merely because the skill says so. +* Capture user-facing validation separately from environment failures. GitHub's existing dependency advisory notice appeared during the docs push, but no dependency scope was added to this release task. + +## Final outcome + +Verified complete on 20 November 2026: v2.21.0 is the latest stable GitHub release, with the supplied release notes and the corrected configuration key. The /v2 Go module resolves to release commit 8c18c8412c9edc79d24e982c43a3ef58867a44af. Netlify production serves the final documentation main commit ce1d18c0b678709166f56c86d714e1df1753ab02, and follow-up GitHub Pages run 44724044831 passed both build and deployment. + +Both development branches are retained remotely and locally. Their trees match their respective main branches, main is an ancestor of development, and both local working trees are clean. No squash or merge commits were used for release promotion. No major version was created. + +Classification: release process documentation and future automation opportunities. All release-blocking environment issues were resolved using temporary process settings or approved CLI access. The proposed version was the requested minor release, so no version decision needed user clarification. Dependency advisory notices and pre-existing unrelated validation issues remain separate maintenance work. + +Next step: turn the recorded successful phases into maintained guidance or a workflow, starting with a version guard, long-lived branch retention, tag availability, and a theme-release-to-documentation hand-off. Do not automatically replay temporary cache paths or repository-wide setting changes without checking the future environment. -- Gitblit v1.10.0