| name | cut-fission-release |
| description | Use when preparing fission.io docs for a new Fission release (e.g. "new release v1.X.0", "create release notes page", "prepare for release"). Orchestrates the config.toml bump, release-notes page, compatibility matrix, What's New card, reference-doc regen, and the single-branch PR. |
Cut Fission Release
Overview
A Fission release touches a predictable set of files on this site.
The single non-obvious thing: the GitHub release body is just the goreleaser template (a flat "What's Changed" PR list), so you must author the Upgrade Notes / Highlights / Fixes yourself from the PR titles and the linked GHSA/PR descriptions — never paste the GitHub body and call it done.
The product code lives at github.com/fission/fission; this repo is docs only.
Version values are decoupled: release_version (app, e.g. v1.24.0) and chart_version (Helm chart, e.g. 1.24.0) move independently.
What changes for every release
| File | Change |
|---|
config.toml | Bump release_version and chart_version (verify both against the chart at the tag) |
content/en/docs/releases/vX.Y.Z.md | New release-notes page (see weight rule below) |
content/en/docs/installation/upgrade.md | New "Upgrade to X.Y.x release" section only if the release has breaking/behavioral changes |
content/en/docs/installation/compatibility.md | Add a literal row for the previous release; update the top shortcode row's columns for the new one (see step 5) |
content/en/_index.html | Replace a What's New card with the release announcement (see step 6) |
content/en/docs/reference/fission-cli/*, crd-reference.md | Regenerated from the new fission binary only if the CLI/CRDs changed (run regen-fission-reference-docs skill) |
static/data/environments.json | Refresh via the update-environments-catalog skill only if environment images changed with the release |
Procedure
1. Pull the release facts from GitHub
The release may still be a draft/prerelease — gh release view finds it anyway.
gh release view vX.Y.0 --repo fission/fission --json body -q .body
Verify the chart facts at the tag (don't assume they match the previous release):
gh api "repos/fission/fission/contents/charts/fission-all/Chart.yaml?ref=vX.Y.0" -q .content | base64 -d | grep -E '^(version|appVersion|kubeVersion)'
gh api "repos/fission/fission/contents/charts/fission-all/values.yaml?ref=vX.Y.0" -q .content | base64 -d | grep -A2 -iE '^internalAuth:'
For any PR that mentions a GHSA or a behavioral change, read its body — that's where the real upgrade detail and accurate wording live:
gh pr view <N> --repo fission/fission --json title,body -q '.title + "\n\n" + .body'
Watch the ?ref=... URLs in zsh — the ? globs. Quote them.
2. Bump config.toml
release_version = "vX.Y.Z"
chart_version = "A.B.C"
These can differ — set each from what you read at the tag.
Never hardcode versions in docs prose; use {{< release-version >}} / {{< chart-version >}} shortcodes there.
3. Create the release-notes page
content/en/docs/releases/vX.Y.Z.md. Weight is reverse-chronological — lower = newer. The newest existing page is the lowest weight; the new page is one less.
(v1.20.5=73, v1.21.0=72, v1.22.0=71, v1.23.0=70, v1.24.0=69 …)
---
title: "vX.Y.Z"
linkTitle: vX.Y.Z
weight: <previous_newest - 1>
---
Section template (copy the most recent release page as the model):
- Upgrade Notes — only if there are breaking/behavioral changes.
A short
{{< notice warning >}} lead-in, then a ### subsection per breaking change spelling out what changed and the action the operator must take.
This page is the canonical home for the per-release upgrade detail — don't push it into the upgrade guide (see step 4).
- Deprecations/Removals — Kubernetes-version support statement, removed fields/routes, dropped tokens, etc.
- Highlights — author 3–6 bullets from the PR titles + GHSA/PR bodies.
Group the security work; name the user-facing features.
- Fixes — notable bug fixes and the chart-version line.
- Changelog → What's Changed — paste the GitHub body's PR list verbatim.
- New Contributors — include only if the GitHub body has it.
No first-time contributors → omit entirely.
- Full Changelog —
https://github.com/fission/fission/compare/vPREV...vX.Y.Z.
- References — upgrade guide, related docs, environments, CRD spec, releases.
4. Upgrade-guide pointer (breaking changes only)
Keep content/en/docs/installation/upgrade.md compact — the per-version detail lives in the release-notes Upgrade Notes (step 3), not here.
Add a short ## Upgrade to X.Y.x release section immediately before the previous version's section (the file is newest-first under the "latest" block): two or three sentences on the nature of the release, then a link to the release notes for the specifics.
## Upgrade to X.Y.x release
vX.Y.0 is a security-hardening release. ... Specs that rely on the rejected primitives will fail admission after upgrade, so review them first.
See the [vX.Y.0 release notes](/docs/releases/vX.Y.Z/#upgrade-notes) for the full list of breaking changes and the action each one requires.
The release page's Upgrade Notes should link back to the general guide (/docs/installation/upgrade/) for the routine CRD/CLI/chart steps.
Don't duplicate the breaking-change detail in both places.
5. Compatibility matrix
content/en/docs/installation/compatibility.md has a Kubernetes table and a KEDA table.
The top row of each uses {{< release-version >}}, so after the config.toml bump it labels itself with the new version automatically — but its data columns still describe the previous release until you update them.
- Insert a literal row for the previous release (copy the old top row's data, replace the shortcode with the literal
vX.Y.Z).
- Update the top row's columns for the new release: built-against = the
k8s.io/api minor in the release's go.mod; tested-with = the kindest/node versions in the release's CI workflows; minimum = the chart's kubeVersion floor; KEDA = the keda version in go.mod/values.
- Update any
kubeVersion notice text if the floor changed.
gh api "repos/fission/fission/contents/go.mod?ref=vX.Y.0" -q .content | base64 -d | grep -E 'k8s.io/api |keda'
6. Homepage What's New card
The landing page announces releases in the "What's New" cards, which are hardcoded in content/en/_index.html (~line 333) — the [[params.whatsnew]] block in config.toml is not referenced by any layout, but keep it in sync anyway.
Replace the stalest card with a RELEASE-badged card: heading "Announcing Fission vX.Y.Z", a one-sentence summary of the headline changes, and a hero-mid button linking /docs/releases/vX.Y.Z/.
7. Reference docs (CLI/CRD), if changed
If the CLI/CRDs changed, run the regen-fission-reference-docs skill.
8. Verify the build
Verify with the verify-hugo-docsy-build skill (pinned Hugo), then confirm the upgrade anchor resolves:
grep -oE 'upgrade-to-12[0-9]x-release' public/docs/installation/upgrade/index.html | sort -u
9. Branch, commit, PR
Keep all release changes on one branch for the user to review and merge.
Do not push or merge unprompted.
If there is an already-open related PR (environments refresh, reference-doc update), it can be folded into the release branch when the user asks.
git switch -c docs-vX.Y.0
git add config.toml content/en/_index.html content/en/docs/releases/vX.Y.Z.md \
content/en/docs/installation/upgrade.md content/en/docs/installation/compatibility.md \
content/en/docs/reference/
git commit
gh pr create ...
public/ and resources/_gen/ are build artifacts — gitignored, never commit them.
Linking rules
- Use plain absolute URLs for in-repo links:
/docs/installation/upgrade/, /docs/releases/vX.Y.Z/.
The dominant repo convention.
- Do NOT use the custom
{{< relref >}} shortcode for content pages — it only resolves section _index.md paths and throws can't evaluate field URL in type page.Page on regular pages, failing the build.
- Use
{{< release-version >}} / {{< chart-version >}} for version strings in prose; the release-notes page title legitimately hardcodes its own version.
- Only link repo files that actually exist at the linked ref — verify each
github.com/fission/*/blob|tree/... URL (e.g. curl -sL -o /dev/null -w "%{http_code}").
- Don't reference internal RFC numbers (RFC-NNNN) in prose — those design docs are not in fission/fission, so the references point at nothing a reader can find.
Describe the change itself instead.
The only acceptable RFC mentions are inside the verbatim "What's Changed" PR-title list.
Common Mistakes
| Mistake | Symptom | Fix |
|---|
| Pasted the GitHub release body as the whole page | Page has a PR list but no real Highlights/Upgrade Notes | Author Highlights/Fixes/Upgrade Notes from PR + GHSA bodies |
| Wrong weight direction | New release sorts below old ones in the sidebar | Lower weight = newer; new page = previous newest − 1 |
Used {{< relref >}} | Build error: can't evaluate field URL in type page.Page | Use absolute /docs/... URLs |
Verified with hugo --gc --quiet | "Clean locally" but Netlify fails | Run via verify-hugo-docsy-build skill (pinned Hugo) |
| Added a "New Contributors" section with no new contributors | Empty/fabricated section | Include it only if the GitHub body has one |
Assumed chart_version == release_version | Wrong chart version published in docs | Read Chart.yaml version at the tag |
Bumped only release_version | {{< chart-version >}} still shows the old chart | Bump both in config.toml |
| Forgot the compatibility matrix | Top (shortcode) row shows the new version with the old release's K8s/KEDA data | Add literal row for previous release; update top-row columns (step 5) |
Edited only [[params.whatsnew]] in config.toml | Homepage still shows the old card | The cards are hardcoded in content/en/_index.html; edit there (step 6) |
Red Flags — Stop
- About to commit a release page whose Highlights are just the raw PR list → write real highlights.
- The new release page's weight is ≥ the previous release's → you have the direction backwards.
(These are the silent failures — they ship without an error. The loud ones, {{< relref >}} build errors and using the wrong build command, are in Common Mistakes above.)
