Generate self-hosted release notes for a Rundeck version using tag-based PR comparison. Use when preparing release notes for a milestone (e.g. 5.17.0), previewing upcoming notes via draft mode, or troubleshooting the notes pipeline.
Instrucciones de origen · Vista previa de solo lectura
name
write-release-notes
description
Generate self-hosted release notes for a Rundeck version using tag-based PR comparison. Use when preparing release notes for a milestone (e.g. 5.17.0), previewing upcoming notes via draft mode, or troubleshooting the notes pipeline.
Write Release Notes
Guides the full release-notes workflow for a Rundeck self-hosted milestone using npm run notes. Auto-loads prerequisites, runs the draft, and helps finalise after tagging.
When to Use
The user asks to "generate release notes", "prepare release notes", "draft release notes for X.Y.Z", or similar.
The user mentions milestones like 5.17.0, 5.18.0 in a release context.
CI or a team member reports the notes pipeline produced unexpected output and help is needed.
Reference Documentation
Read these before executing:
.claude/docs/local-development.md — environment setup (Node via nvm, Cloudsmith token)
.claude/docs/pr-feed.md — the shared utilities (pr-utils.mjs) and tag-parsing logic used by notes.mjs
README.md (repo root) — the authoritative end-to-end release-notes workflow (section: "How to Create Release Notes")
Prerequisites
Node 22.22.0 active (nvm install && nvm use).
Repo dependencies installed (npm install, requires CLOUDSMITH_NPM_TOKEN or .npmrc removed).
.env file at the repo root with GH_API_TOKEN=ghp_... (needs repo scope; must have access to rundeckpro/rundeckpro and rundeckpro/sidecar).
All contributing PRs carry the release-notes/include label.
PR descriptions use a ## Release Notes section for customer-facing copy.
Process
Phase 1: Gather parameters
Before running anything, confirm with the user:
Target milestone (required) — e.g. 5.20.1. If the user has not stated it, ask.
Baseline version (--from-version, optional) — ask the user: "Should I auto-detect the starting version from the previous tag, or do you want to specify it explicitly (e.g. --from-version=5.20.0)?" Auto-detection is the default and usually correct; an explicit baseline is needed for patch releases or unusual ranges.
Phase 2: Run the draft preview (safe — does not modify configs)
Use the form that matches what the user provided in Phase 1:
If the user did not supply --from-version (auto-detect):
npm run notes:draft -- --milestone=<X.Y.Z>
If the user supplied an explicit --from-version:
npm run notes -- --milestone=<X.Y.Z> --from-version=<X.Y.Z-prev> --draft
If the tag v<X.Y.Z> does not yet exist, draft mode falls back to HEAD and prints a warning — this is expected.
Output: docs/history/<major>_x/draft.md.
Review the draft with the user before proceeding.
Phase 3: Tag the release
Only proceed when the user has confirmed the draft content. Split tag creation from pushing so the user can confirm each step.
Create the local tag:
git tag v<X.Y.Z>
Push the tag ONLY after the user explicitly confirms (Critical Rule: never push without explicit instruction):
git push origin v<X.Y.Z>
Phase 4: Generate final notes (updates configs)
npm run notes -- --milestone=<X.Y.Z>
This updates, in addition to the notes markdown:
docs/.vuepress/setup.js — version info
docs/.vuepress/sidebar-menus/history.ts — sidebar link
docs/.vuepress/navbar-menus/about.js — navbar link
Use git status to confirm no additional side-effect files were modified; stage any that appear.
Do NOT push without the user's explicit instruction.
Phase 7: Push (only on explicit instruction)
Once the user confirms, push the commit (and, if not already pushed, the tag):
git push
git push origin v<X.Y.Z> # if not already pushed in Phase 2
Version Auto-Detection
Target
Auto-detected previous
Compares
5.17.0
5.16.0
v5.16.0 → v5.17.0
5.17.1
5.17.0
v5.17.0 → v5.17.1
5.0.0
4.17.0
v4.17.0 → v5.0.0
If the user provides --from-version, pass it explicitly (Phase 2 explicit form). Otherwise, auto-detection is used. Ask the user in Phase 1 if the milestone is a patch release and the baseline is ambiguous.
Troubleshooting
Symptom
Cause / Fix
Tag X.Y.Z not found in draft mode
Normal before tagging — draft uses HEAD. Ignore.
Tag X.Y.Z not found in final mode
Create the tag first (Phase 2).
GH_API_TOKEN environment variable is not set
Create .env with a GitHub token with repo scope.
No PRs found
Verify tags exist, PRs are merged (not just closed), and carry release-notes/include.
Warnings about docs / ansible-plugin repos
Expected — those repos do not use version tags; they are skipped gracefully.
Checklist
Node version matches .nvmrc
.env present with valid GH_API_TOKEN
Draft generated and reviewed with the user
Git tag created and pushed
Final notes generated
Manual edits applied (date, overview)
All config files staged together with the notes markdown
Commit message follows Release notes for <X.Y.Z> convention
