ITADN

Generate rich GitHub Release notes from the feature ledger

#527Closedjoelkoz 创建于 2026-07-15
J
joelkozcommented
## Summary Generate rich **GitHub Release notes** automatically from the feature ledger introduced in #524, so each release documents its new features (with usage notes) and improvements up front, and lists fixes/other changes after. The Signal K App Store's "Changelog" tab renders a package's **GitHub Release body** as Markdown (it reads the repo's releases feed, not `CHANGELOG.md`). So the release notes must be written onto the GitHub Release itself. Today FSK relies on GitHub's default auto-generated notes (a flat list of PR titles); this issue replaces that with a curated, grouped changelog derived from the same corpus that powers the Feature Browser. Depends on #524 for the ledger schema. Independent of the browser UI — this is a repository tool plus a workflow change. ## Design A **deterministic CLI tool** lives in `dev-tools/` (developer-only, not shipped in the npm package; CI runs it from the full checkout). It transforms the ledger into Markdown — no judgement, no external services — so any maintainer gets the same output, and the result is unit-testable. Two modes: - **`stamp <version>`** — fills in the blank `since` field on the ledger rows that are new in this release. Run from a `version` npm lifecycle hook so `npm version` re-stages the stamped ledger into the version-bump commit. No manual step required. - **`render <tag>`** — emits the full Release body: - **New Features** — ledger rows for this release with `kind: new`. - **Improvements** — ledger rows for this release with `kind: enhanced` (using each row's `note`). - **Fixes / Other** — generated by the tool: fetch the PRs merged in the tag range and **exclude any PR already present in the ledger** (new/enhanced/skip), then group the remainder by conventional-commit type from their titles. The tool owns the **entire** body. Notably, `generate_release_notes` must be turned **off** in the release workflow — leaving it on would list every feature twice (once as a rich entry, once in the auto PR list). ## Workflow wiring - `release.yml` runs `render <tag>` on tag push and passes the output to the release action via `body_path`, so a plain tag push produces the full changelog with no local step. - A bad or failed render is not stuck: the GitHub Release body is freely editable after publish, editing it does not re-trigger the workflow, and it is independent of the (immutable) npm publish. ## Acceptance criteria - [ ] `dev-tools/` CLI with `stamp` and `render`, excluded from the shipped package, runnable in CI. - [ ] `stamp` fills blank `since` for the release's rows and is invoked from a `version` hook so the bump commit carries the stamps. - [ ] `render` produces New Features + Improvements from the ledger and a Fixes/Other section from non-ledger PRs, grouped by type. - [ ] `release.yml` uses the rendered body via `body_path`, with `generate_release_notes` disabled (no double-listing). - [ ] Unit tests over representative ledger + PR inputs assert the exact rendered Markdown (deterministic). ## Related work - Consumes the `features/` ledger from #524; part of the same initiative. - Built after the #524 → #525 → #526 chain (it depends only on #524's settled ledger format). </content>
关闭于 2026-07-16 0 条评论