CaskHub Release Notes

Overview

CHANGELOG.md at the repo root (Keep a Changelog style: cumulative, newest first) is the single source. Scripts/release.sh uses the TOP entry as the GitHub release body, and the five most recent entries (NOTES_HISTORY) as the Sparkle update dialog notes (embedded into appcast.xml, rendered as markdown), so users who skipped releases still see what changed. Feature-PR descriptions are not covered by this standard — keep them as detailed as you like. The release PR is the exception (see Release PR description below).

Format

Each release adds one entry at the top of CHANGELOG.md:

## x.y.z — YYYY-MM-DD

### What's New

- Bullet per user-visible feature

### Improvements

- Bullet per enhancement to something that already existed

### Bug Fixes

- Bullet per user-visible fix

• The top ## header MUST be the version being cut — release.sh aborts on mismatch, so forgetting to add the new entry fails loudly.
• Omit any section that would be empty. A patch release may be Bug Fixes only.
• Never rewrite past entries; only add the new one on top.
• When the new entry has a ### What's New section, update the launch card. Patch releases leave it alone.
  • CaskHub/Resources/WhatsNew.xcstrings holds one featureN.title and featureN.detail pair per row, up to four rows. Rewrite the whole file with the new English text and no other locales. The keys are reused, so a translation left behind would show the previous release's text.
  • In WhatsNewRelease.latest (CaskHub/Models/LaunchCard.swift) set the version and each row's SF Symbol, and match the row count to the file.

Writing the bullets

Source material: git log --oneline --first-parent <prev-tag>..HEAD and the merged PR titles/descriptions since the last release.

• User-facing language: say what changed for the user, not how it was built ("Faster search results", not "Refactored CaskRepository query path").
• Start each bullet with a verb (Added / Fixed / Improved…), sentence case, no trailing period, one line each.
• Collapse related minor fixes into one bullet; aim for ≤6 bullets a section.
• Never include: back-merge PRs ("master to develop"), version-bump/appcast commits ("release: x.y.z"), CI/workflow changes, test-only changes, refactors or dependency bumps with no user-visible effect, PR numbers, commit hashes.
• If literally everything in the range is internal, write one honest bullet under Improvements ("Under-the-hood stability improvements") rather than padding.

Release PR description

The release/x.y.z → master PR body is two parts, in order, and nothing else:

1. Changelog — the version's What's New / Improvements / Bug Fixes bullets (the same content that ships as the release notes).
2. Release artifacts — a short list of what the build produced: the notarized zip and build number, the appcast update, the README bump, dSYMs.

Merging behavior lives in the runbook and the publish-release.yml / sync-develop.yml workflows, not in the PR body.

Example entry

## 0.7.0 — 2026-08-02

### What's New

- Added import and export for your installed app list

### Improvements

- Faster cask search while typing

### Bug Fixes

- Fixed Homebrew repair getting stuck after relaunch
- Fixed update badge showing for already-updated casks