release-changelog

# Voiden release changelog workflow ## Sibling repositories This repo (`voiden`) is one of three under `~/Desktop/Voiden/` — know all three before starting release work, since a release routinely touches more than one: - **`voiden`** (this repo) — the app monorepo. Owns `apps/ui/src/data/changelog.json` (full technical changelog) and `apps/ui/src/core/whats-new/whats-new.json` (in-app highlights). - **`../Voiden Website/website`** — the public marketing site. Mirrors the technical changelog at `src/features/changelog/data.ts`, rendered by `src/components/ChangelogEntry.tsx`. Same content as `changelog.json`, different schema (see part 3 below) — keep both in sync every release, don't let the website fall behind (it had silently missed three whole releases before this note existed). - **`../docs`** — the docs site (docs.voiden.md, Docusaurus). No changelog here, but a release that adds or changes a user-facing feature (a new block, a new CLI flag, a new panel) usually means a doc page needs updating too. This skill doesn't write those doc edits itself — but check whether one's needed, and say so, rather than closing out release work as if the changelog were the only thing that could be stale. When asked to create a changelog entry for a new app version, **three files across two repos** need updating, not one. They serve different audiences and have different formats — do not skip any of them or copy the same content in verbatim where the format actually differs. ## 1. `apps/ui/src/data/changelog.json` — full technical changelog The exhaustive, engineering-facing record. One object per release, prepended to the top of the array (newest first). ```json { "version": "vX.Y.Z", "date": "DD/MM/YYYY", "title": "Short Punchy Title", "description": "1-2 sentence summary of the release for the changelog page header.", "icon": "Wrench", "iconColor": "text-orange-400", "bgColor": "bg-gradient-to-br from-slate-900 to-orange-950", "changes": { "Added": ["..."], "Improved": ["..."], "Fixed": ["..."] } } ``` - Only include `"Added"`/`"Improved"`/`"Fixed"` keys that actually have entries for this release. - **Each bullet is ONE line** — a single short sentence or clause, like Bruno's and Yaak's changelogs (`fix: stop AWS V4 auth headers from leaking on cross-origin redirects`). Name what changed, not the mechanism — no "because", no multi-clause backstory, no explaining *why* it broke or *how* it was fixed internally. If it takes more than one line to read, cut it down to the user-visible outcome only. An issue/PR number in parens (`(#523)`) is fine and matches the file's existing convention. - **Title/description stay neutral about the past.** Don't phrase a fix as "X Actually Works Now" or "X Finally Fixed" — that reads as an admission the feature never worked, which isn't the tone a release note should take even when it's technically true. State what changed ("X Connection Fix", "X Reliability Fix"), not a verdict on the prior state. - Derive content from `git log <previous-changelog-commit>..HEAD`, scoped to user-facing changes — skip pure CI/release-pipeline commits (npm publish config, GitHub workflow tweaks, signing, packaging scripts) unless they're user-visible (e.g. "Windows installer now signed correctly"). - **Contributor credit, with a real link.** For every change whose commit/PR author isn't the core team, append ` — contributed by [@username](https://github.com/username)` to that bullet. Don't guess the username from the commit's git author name or email — look it up for certain: - `git log <range> --format="%an <%ae>"` to see who committed in this release's range. - For each non-core author, find their PR number (commit message usually has `(#123)`) and confirm the real GitHub login with `gh pr view <number> --repo VoidenHQ/voiden --json author -q .author.login` — a `noreply.github.com` commit email often encodes the username directly, but don't rely on that alone (a personal/work email tells you nothing); the PR lookup is the source of truth. - This renders as a real clickable link in the app (`ChangeLogScreen.tsx` parses the `[text](url)` shape specifically for this) — always use that exact markdown-link form, not a bare URL or plain username. - Check every contributor's change actually made it into a changelog bullet — it's easy for a real fix to ship without ever getting written up. Cross-check `git log <range> --format="%an"` against what you're about to write, and add a bullet for anything missing rather than only covering what an existing draft already mentions. - Pick an icon from the existing set already used in the file (`Wrench`, `Sparkles`, `Bug`, `Plug`, etc.) — reuse for consistency, vary the color so consecutive releases don't look identical. - Validate with `node -e "JSON.parse(require('fs').readFileSync('apps/ui/src/data/changelog.json','utf8')))"` after editing. ## 2. `apps/ui/src/core/whats-new/whats-new.json` — in-app "What's New" highlights A **curated, marketing-toned** subset shown in the in-app spotlight/modal (`apps/ui/src/core/whats-new/WhatsNewModal.tsx`). Prepend a new release object to `releases` (newest first): ```json { "version": "X.Y.Z", "date": "Month YYYY", "whatsnew": [ { "icon": "🌱", "title": "Short Title", "description": "User-facing sentence or two, written for someone who didn't read the technical changelog — explain the *benefit*, not the implementation." } ] } ``` - Version string has **no leading `v`** here (unlike `changelog.json`), and `date` is `"Month YYYY"`, not `DD/MM/YYYY`. - Pick 2-4 of the most user-visible items, not every bullet from the technical changelog. Bundle a batch of minor/internal fixes into one "🐛 ... Fixes" entry rather than listing each separately — see existing `2.0.1`/`2.1.0` entries in the file for tone and granularity. - A release that's pure CI/infra/internal cleanup with nothing user-visible can be skipped here (it's fine for `whats-new.json` to jump versions) — but if you added a changelog entry because there *was* user-facing change, add a whats-new entry too. - Use real emoji for `icon` (not Lucide icon names — that's `changelog.json`'s convention, this file is different). - Validate the same way after editing. ## 3. `../Voiden Website/website/src/features/changelog/data.ts` — website mirror Same content as `changelog.json`'s entry (part 1) — same bullets, same one-line rule, same contributor links — but a different schema, in a **different repo** (`Voiden Website/website`, a sibling of this one, not a subdirectory of it). Prepend to the top of the `changelogs` array: ```ts { version: "X.Y.Z", // no leading "v", unlike changelog.json date: "YYYY-MM-DD", // ISO, unlike changelog.json's DD/MM/YYYY title: "Short Punchy Title", description: "Same 1-2 sentence summary as changelog.json.", icon: "Wrench", iconColor: "text-orange-400", bgColor: "bg-gradient-to-br from-slate-900 to-orange-950", changes: [ { type: "added", items: ["..."] }, { type: "improved", items: ["..."] }, { type: "fixed", items: ["..."] }, ], } ``` - `changes` is an **array of `{type, items}` objects** here (lowercase `type`: `added`/`improved`/`fixed`/`changed`/`notes`), not a keyed object like `changelog.json`'s `Added`/`Improved`/`Fixed`. Don't paste one shape into the other's file. - Contributor links use the identical `[@username](https://github.com/username)` markdown-link text — `ChangelogEntry.tsx` parses that exact shape the same way `ChangeLogScreen.tsx` does on the app side. Keep both parsers' regex (`CHANGE_LINK_RE`) in sync if either ever changes. - Validate with `npx tsc --noEmit -p tsconfig.json` (run from the website repo root) after editing — it's a `.ts` file, not JSON, so `JSON.parse` won't catch a syntax error here. - This file has drifted behind `changelog.json` before (three releases went unmirrored) — when in doubt, diff the top few entries of both files before assuming the website is current. ## Order of operations 1. Check `git log` since the last changelog entry's commit to know what actually shipped. 2. Write the `changelog.json` entry first (full detail). 3. Distill 2-4 highlights from it into a `whats-new.json` entry. 4. Mirror the same entry into the website's `data.ts` (part 3) — same content, different schema, different repo. 5. Validate all three files (two JSON parses + one `tsc --noEmit`). 6. If this release shipped a new or changed user-facing feature, check `../docs` for a page that now needs updating — flag it even if you're not the one writing that doc pass right now.