Feature: Formatted Changelog

[decepulis]

Note

Triage estimate — cycle priority and story points were assigned during an AI-assisted planning pass and are rough first guesses. Confirm or adjust when you pick this up.

Overview

Generate a human-readable changelog for each release and publish it on the docs site. The raw CHANGELOG.md (generated by git-cliff) is a bullet list of commits — useful for completeness, but not for understanding what changed and why it matters.

Two-phase pipeline

Phase 1 — Pre-release (mechanical, in release-pr.yml):
After git-cliff generates CHANGELOG.md, a new step extracts the latest release section and writes it to site/src/content/changelog/{version}.md with frontmatter. This gets committed to the release PR alongside version bumps and the raw changelog. The site always has something for each release immediately.

Phase 2 — Post-release (LLM, new workflow):
A separate workflow triggers on release published. It reads the raw changelog file, gathers deep context (PR bodies, PR review comments, linked issues, parent epics), and calls an LLM to rewrite the body into narrative prose. The LLM also adds a description to the frontmatter. The result is opened as its own PR so it can be reviewed without blocking the release.

Why separate?

Review of the LLM-generated prose takes longer than review of the mechanical changelog. We don't want to slow down releases. The LLM PR can land on its own schedule — even after the release ships.

Frontmatter schema

description: ...               # optional — LLM adds a one-sentence narrative summary
date: 2026-03-19               # release date, from git-cliff
version: 10.0.0-beta.7        # semver, for sorting/filtering
prerelease: true               # mechanical, from release-please config
breaking: false                # mechanical, from git-cliff parsing
compareUrl: https://github.com/...  # optional, from git-cliff footer

description is optional before the LLM pass.

LLM behavior

The LLM follows our writing-style.md (direct, confident, no filler). It:

• Leads with the 1–3 most impactful changes, informed by epic context
• Groups related PRs that ladder up to the same epic into one cohesive story
• Calls out breaking changes with migration guidance from PR bodies/comments
• Summarizes smaller fixes briefly rather than listing each one
• Skips internal-only changes (CI, tooling, changelog plumbing)
• Does not speculate, market, or fabricate — sticks to what the PRs say

Sub-issues

1. Actions pipeline — .gitkeep, release-pr.yml step, post-release LLM workflow
2. Backfill — parse existing CHANGELOG.md to generate raw changelog files for beta.1 through beta.6
3. Site UI — add changelog content collection to content.config.ts, build the changelog page(s), clarify relationship between release blog posts, migration guides, and changelog entries