Release Notes

Release Notes — Poracode

Turn a release's PRs, complete commit range, and actual code diff into a curated, human-readable changelog entry that reads like a person wrote it — and keep every release in the changelog consistent in voice, shape, and length.

Poracode's changelog is curated data, not auto-generated. GitHub already auto-lists merged PRs on the Release page; this skill produces the hand-written layer that ships inside the app (Settings → Changelog, the "What's New" dialog) and on the marketing site.

When to use

• The user asks to add/write release notes, update the changelog, or "do the changelog for vX.Y.Z".
• A release was just tagged/published and the in-app + website changelog need an entry.
• Backfilling missing releases into the changelog.

When NOT to use

• Editing the mechanics of the changelog feature (the React surfaces, the seen-state gate) — that's normal code work, not this skill.
• Writing a single commit message or a GitHub Release body (GitHub generates that).

The one file you edit

There is a single source of truth: website/public/changelog.json on master. The marketing site serves it at https://www.poracodeapp.com/changelog.json and the desktop app fetches + caches it at runtime, so editing this one file (and pushing to master, which redeploys the site) updates both surfaces without an app rebuild.

Shape — an object with a newest-first releases array (do not invent fields):

{
  "releases": [
    {
      "version": "1.3.1",
      "date": "2026-06-17",
      "title": "Short punchy headline, NO version number",
      "summary": "One or two sentences — the release's elevator pitch.",
      "changes": [
        {
          "kind": "added",
          "label": "Projects",
          "text": "One complete, user-facing sentence."
        },
        { "kind": "fixed", "text": "A mixed-scope fix that needs no forced label." }
      ]
    }
  ]
}

kind is one of added | improved | fixed. Release-note text stays English (it is not localized — only the surrounding app UI chrome is). label is an optional short feature or product prefix; labeled and unlabeled changes may appear in the same release.

Step 1 — Gather source material

Resolve the repo slug from the remote (default Porabuild/Poracode):

gh repo view --json nameWithOwner -q .nameWithOwner

Then collect, for the target version:

• The release date and the auto-generated PR list (the body):

  gh api repos/<owner>/<repo>/releases/tags/v<X.Y.Z> --jq '{date: .published_at, body: .body}'

• The complete git range, even when a GitHub release and PR list exist. PRs are supplementary, not authoritative: direct commits, local merges, and squash details may be absent. Read every commit subject and body, inspect the range-level file list and diffstat, then inspect the substantive patches and nearby tests before writing:

  git log --date=iso-strict --pretty='format:%H%n%ad%n%s%n%b' <previousTag>..<target>
  git diff --stat <previousTag>..<target>
  git diff --name-status <previousTag>..<target>
  git diff <previousTag>..<target>

  Do not infer behavior from commit titles alone — open the patch when the subject is ambiguous (especially feat/fix that touch UI, settings, i18n, or provider adapters).
• An unpublished target boundary, when no target tag exists. Use the intended release commit (usually HEAD), confirm its package version matches the requested version, and state this boundary in the handoff rather than pretending the tag exists.
• The maintainer's highlight notes, if they pasted any (Telegram/X-style bullets, "now with: …"). These are authoritative for what matters most — lead with them. If the user didn't provide notes and the release is large, ask once whether they have highlights; otherwise proceed from the collected release metadata and git evidence.

Step 1b — Commit disposition ledger (mandatory)

Before drafting prose, walk every non-merge commit in <previousTag>..<target> and assign one disposition. Keep this ledger in your working notes (it does not ship in changelog.json, but you must not skip it):

Always-include signals (treat as include or fold, never silent omit):

• New or changed user-visible copy — especially commits that add msgids / touch src/renderer/locales/**/messages.po (or mobile/website locale catalogs). New strings almost always mean a user can see something new.
• Discoverability / selection-state UI: mode-specific icons, badges, trigger labels, selected-state highlights, status chips, empty states, onboarding hints. These stay even when the underlying feature shipped in an earlier release — users notice the clarity, and "polish on an existing feature" is still improved, not noise.
• Settings, menus, tooltips, toasts, dialogs, composer controls, sidebar chrome, Git/PR controls, provider pickers — anything the user clicks or reads in the app.
• Behavior fixes the user would have hit (done-state, wrong window size, broken launch).

Safe to omit (with an explicit reason):

• Tests, type-only refactors, CI, lockfile-only, version bumps, pure renames without product behavior, dependency upgrades with no user-visible effect.
• Micro-animation / fade / layout-pixel tweaks that do not change what the control means or how the user finds it.
• Marketing-site-only changes (website/** that do not affect the shared changelog.json data or in-app surfaces) — mention only when they are a real product surface (e.g. a new About page, pairing flow). Sticky nav on the public changelog page is optional; prefer app-facing notes when distilling.

Anti-pattern that caused a real miss (1.6.1): a small feat(pr-watch) that only swapped the PR automation trigger icon/label per Auto Fix vs Auto Merge was dropped while larger sidebar/workspace bullets dominated. It touched every locale catalog and changed what users see on every automated PR — that is include as improved, not "too small to list."

Reconciliation gate: every feat/* and fix/* commit that touches src/renderer/**, src/mobile/**, src/shared/messages.ts, or locale catalogs must end as include or fold into …. If you cannot fold it cleanly, give it a bullet.

Quick helpers when auditing:

# Commits that added/changed localized strings (strong user-facing signal)
git log --pretty='%h %s' --name-only <previousTag>..<target> -- 'src/renderer/locales/**'
# UI / settings / PR surfaces in the range
git log --pretty='%h %s' --name-only <previousTag>..<target> -- \
  'src/renderer/**' 'src/mobile/**' 'website/src/**'

Step 1c — Prior Art & History Cross-Check (Mandatory Anti-Hallucination Gate)

Never assume a feature is brand new. Before writing bullets, cross-check previous releases in website/public/changelog.json:

# Search existing changelog for mentions of the area or feature
grep -in "<feature-keyword>" website/public/changelog.json

1. Verify Lineage:

   • If GitHub Actions, Plugins, Workspaces, Archived Threads, or Provider Switching are in the commit range, check what already existed in prior versions.
   • If the capability already existed, do NOT write "You can now <basic action>" as an added bullet. That is a hallucination of novelty.
   • Accurately describe the delta / upgrade as improved (e.g. "GitHub Actions now supports multiple signed-in accounts", "Switching providers now continues inside the same thread (Handoff 2.0)", "Archived thread management is redesigned for multi-workspace and remote filtering").

2. Differentiate Plumbing from User Benefits:

   • Do NOT list internal architecture or IPC/notification mechanics as user bullets (e.g. avoid "task notifications and background task updates" or "added database sync migrations and Zod schemas").
   • Distill the user outcome: what can the user now do or see? (e.g. "Run Antigravity via first-class ACP runtime support with live usage discovery and machine-scoped settings").

3. Check Environment & Scope Support:

   • Check if changes expanded platforms (e.g. WSL, remote SSH, Windows shell resolution, multi-machine settings). Mention platform support explicitly when added.