prepare-release

Prepare Release

Overview

Prepare a new release by generating changelog entries, updating version references, and creating release notes.

Usage

/prepare-release

Release Authority and Automation

Do not create release tags just because this skill was invoked. By default, prepare only.

When Karim explicitly says to do the release (for example "release time" or "do the release"), run the full local release gates, create and push the annotated tag yourself, then confirm the lightweight publication workflow.

Default job:

• Prepare the changelog
• Update version references
• Generate release notes draft
• Commit preparation changes

Maintainer-authorized release job:

• Verify master is clean and up to date
• Verify the release tag does not already exist locally or remotely
• Create and push the annotated tag
• Let .github/workflows/publish-release.yaml publish the already-verified tag
• Confirm the workflow and GitHub release succeeded

Current Release Automation

The repository has tag-driven release automation in .github/workflows/publish-release.yaml.

Important details:

• The workflow runs only on pushed v* tags and has no manual-dispatch path.
• It extracts the Markdown release content from CHANGELOG.md, specifically everything under ## [Unreleased] until the next ## [ heading.
• It rejects a missing, duplicate, or empty [Unreleased] section.
• It asks GitHub to append generated release notes.
• It creates the GitHub release with ncipollo/release-action.
• It does not run Terraform, Packer, HCloud, bootstrap, or cluster gates. Those are authoritative local pre-tag checks.

Therefore:

• CHANGELOG.md is the release-content Markdown file.
• Keep the target release notes under ## [Unreleased] until after the release tag is pushed.
• Do not move [Unreleased] to [vX.Y.Z] - YYYY-MM-DD before tagging unless you are also bypassing the workflow and manually providing release notes.
• Do not run gh release create during the normal path; the tag workflow owns publication. Use it only after re-running the local integrity gates if publication fails.
• If Karim asks for a tiny release-prep correction during release, commit it on the release branch, merge it through the protected master pull-request path, then tag the resulting merged commit.
• After a successful release, cut CHANGELOG.md: reset ## [Unreleased] to an empty placeholder and move the released notes under ## [X.Y.Z] - YYYY-MM-DD. Merge that cleanup through a release-maintenance pull request.
• Previous release notes must never remain under ## [Unreleased]; otherwise the next tag workflow will publish stale notes again.
• For v3-series releases, verify README's compact "Current release:" link points at the latest release tag and CHANGELOG.md carries the release content.
• After significant releases, regenerate the machine-readable knowledge file (kube-hetzner-knowledge.jsondata) and confirm its meta.version matches the release. The Custom GPT was retired 2026-07-13 — the agent skills (installed via npx skills add kube-hetzner/terraform-hcloud-kube-hetzner) are the assistant channel; the knowledge file feeds future tooling (MCP).

Contributor Credit (SUPER IMPORTANT)

GitHub-generated notes and the changelog expose the people whose work landed since the previous tag. Original PR submitters MUST remain visible — credit where credit is due.

• Upstream requirement (enforced at merge time, see the review-pr skill): community contributions keep the contributor as commit author in master history. Squash only when merging a contributor-only PR directly; use a merge commit when we pushed fixes on top; cherry-pick with preserved authorship or Co-authored-by: trailers only when partially adopting or porting work.
• Promotion or major integration PRs, such as the v3 staging-to-master train, must merge with a merge commit. Never squash those PRs; squashing erases the per-commit community authors that feed repository and release credit.
• Pre-tag check: git log <prev-tag>..HEAD --format='%an <%ae>' | sort -u — every community contributor whose fix is in the release must be listed. If someone is missing, fix history/credit BEFORE tagging (after tagging it is public and immutable).
• Pre-tag disposition check: every fully accepted community PR must have a non-null mergedAt. For PRs integrated indirectly through a release branch, also verify the recorded headRefOid is an ancestor of the release target. A closed-but-unmerged accepted PR is a release-process defect; repair the integration before tagging instead of compensating with comments.
• Post-release check: generated notes and changelog thanks must include the original submitters, not just maintainers. If someone is missing, treat it as a release defect and edit the release body.
• Changelog entries for community fixes reference their PR/issue numbers so the human credit is also visible in prose.

Workflow

digraph release_flow {
    rankdir=TB;
    node [shape=box];

    analyze [label="1. Analyze changes since last release"];
    classify [label="2. Classify release type"];
    changelog [label="3. Update CHANGELOG.md"];
    badges [label="4. Update version badges"];
    gpt [label="5. Update GPT knowledge"];
    notes [label="6. Verify CHANGELOG.md release content"];
    commit [label="7. Commit preparation"];
    release [label="8. If explicitly authorized: tag + monitor workflow"];

    analyze -> classify;
    classify -> changelog;
    changelog -> badges;
    badges -> gpt;
    gpt -> notes;
    notes -> commit;
    commit -> release;
}

Step 1: Analyze Changes

REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)

# Get latest release tag
LATEST=$(gh release list --repo "$REPO" --limit 1 --json tagName --jq '.[0].tagName')
echo "Latest release: $LATEST"

# List commits since last release
git log $LATEST..HEAD --oneline

# Get detailed changes
git log $LATEST..HEAD --pretty=format:"- %s (%h)"

Read the commit list and diff directly. Trace user-facing changes to their changelog entries and classify them as features, bug fixes, breaking changes, or documentation. Ignore internal refactors unless they alter behavior.

Step 2: Classify Release Type

Type	When	Example
PATCH (x.x.X)	Bug fixes, docs, deps	2.19.1
MINOR (x.X.0)	New features, backward compatible	2.20.0
MAJOR (X.0.0)	Breaking changes	3.0.0

Breaking Change Indicators

• Variable removed or renamed
• Default value changes behavior
• Resource naming changes (causes recreation)
• Required migration steps

Obtain the mandatory independent review of breaking-change and resource- recreation risk. Give the reviewer the exact release diff and require a final verdict with concrete file and line references; verify every finding against the code and upgrade-plan evidence.

Step 3: Update CHANGELOG.md

Changelog Format

## [Unreleased]

### ⚠️ Upgrade Notes
<!-- Migration guides, breaking change warnings, special upgrade steps -->

### 🚀 New Features
<!-- New functionality added -->

### 🐛 Bug Fixes
<!-- Bugs that were fixed -->

### 🔧 Changes
<!-- Non-breaking changes, refactors, improvements -->

### 📚 Documentation
<!-- Documentation updates -->

Writing Good Entries

• Write from user's perspective
• Include issue/PR references: (#1234)
• Be specific about what changed
• Include migration steps for breaking changes

Example Entries

### 🚀 New Features
- **K3s v1.35 Support** - Added support for k3s v1.35 channel (#2029)
- **NAT Router IPv6** - NAT router now supports IPv6 egress (#2015)

### 🐛 Bug Fixes
- Fixed autoscaler not respecting max_nodes limit (#2018)
- Resolved firewall rules not applying to new nodes (#2012)

### ⚠️ Upgrade Notes
- **NAT Router users**: Run `terraform apply` twice after upgrade due to route changes

Step 4: Update Version Badges

Update README.md badges if version references changed:

[![K3s](https://img.shields.io/badge/K3s-v1.36-FFC61C?style=flat-square&logo=k3s)](https://k3s.io)

Check versions.tf for:

• Terraform version requirement
• Provider version requirements
• K3s default channel

Step 5: Update Knowledge File (if applicable)

If significant changes, regenerate the machine-readable knowledge file (Custom GPT retired 2026-07-13; this feeds future tooling such as the planned MCP server):

1. Use the maintained knowledge-generation workflow/artifact for this repo or operator environment.
2. Update the generated file's meta.version to the release being prepared.
3. Re-open the generated artifact and verify the version plus the release's major operational facts.

Do not invent a checked-in generator path if one is not present in the worktree.

Step 6: Verify Release Notes Content

Normal path: the release notes draft is the CHANGELOG.md content under ## [Unreleased]. Make sure it contains the target release section, issue/PR references, upgrade notes if any, and no stale placeholder text.

Preview exactly what the workflow will extract:

awk '/^## \[Unreleased\]/{flag=1; next} /^## \[/{flag=0} flag' CHANGELOG.md

If a separate release-notes file exists in a future train, use it as a drafting aid, but copy the final release content into CHANGELOG.md under ## [Unreleased] before tagging so the automation can consume it.

Before tagging a v3 release, run the local readiness gates:

terraform fmt -recursive
terraform-docs markdown table --config .terraform-docs.yml --output-mode inject --output-file docs/terraform.md .
terraform init -backend=false -input=false
terraform validate -no-color
tmpdir="$(mktemp -d)"
rsync -a --exclude .git --exclude .terraform --exclude .terraform-tofu ./ "$tmpdir"/
(cd "$tmpdir" && tofu init -backend=false -input=false && tofu validate -no-color)
rm -rf "$tmpdir"
uv run scrip

---

*Content truncated.*