Changelog and What's new: CHANGELOG.md cut into each release, shown in the update band, a What's new card and once after updating

CHANGELOG.md keeps an Unreleased section (user-facing changes add a line in
the same commit); tool/release.sh cuts it into the version, the manifest
gets a structured "changes" field next to the one-line "notes" older
apps read, and the Gitea release text is that section. The app's update
band shows the top items, What's new opens a card (Added / Changed /
Fixed), and the first start after an update shows it once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tool/release.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 # Cut a release without typing a version anywhere: derives the next
-# version (patch by default), bumps all three pubspecs in lockstep,
-# writes updates/manifest.json (predictable asset URL — no CI roundtrip
-# needed), commits, and tags. Review, then `git push --follow-tags` —
+# version (patch by default), turns CHANGELOG.md's Unreleased into that
+# version (refuses when it has no items), bumps all three pubspecs in
+# lockstep, writes updates/manifest.json (predictable asset URL — no CI
+# roundtrip needed; `notes` and `changes` from the changelog), commits,
+# and tags. Review, then `git push --follow-tags` —
 # CI takes it from there (build, Forgejo release, asset upload).
 # Usage: tool/release.sh [patch|minor|major] [--dry-run]
 set -euo pipefail
@@ -41,9 +43,25 @@ if git -C "$ROOT" rev-parse "v$VER" >/dev/null 2>&1; then
 fi
 echo "release will be v$VER ($WHY)"
 
+# What people read (the update band, What's new, the release page) is
+# CHANGELOG.md's Unreleased: no items, no release.
+CHANGES="$(dart "$ROOT/tool/changelog.dart" json unreleased)"
+COUNT="$(python3 -I -c 'import json,sys; print(sum(map(len, json.loads(sys.argv[1])["changes"].values())))' "$CHANGES")"
+if [[ "$COUNT" == "0" ]]; then
+  echo "error: CHANGELOG.md's Unreleased has no items — write what changed for people first" >&2
+  exit 1
+fi
+if [[ -z "$(sed -n '/^## Unreleased/,/^### /{/^#/d;p}' "$ROOT/CHANGELOG.md" | tr -d '[:space:]')" ]]; then
+  echo "warning: Unreleased has no summary line; older apps (which show only notes) get its first items" >&2
+fi
+echo "changelog for v$VER:"
+dart "$ROOT/tool/changelog.dart" markdown unreleased "$VER" | sed 's/^/  /'
+
 if [[ "$DRY" == "1" ]]; then
   exit 0
 fi
+dart "$ROOT/tool/changelog.dart" cut "$VER"
+CHANGES="$(dart "$ROOT/tool/changelog.dart" json "$VER")"
 for f in $PUBSPECS; do
   sed -i -E "s/^version: .*/version: $VER/" "$ROOT/$f"
 done
@@ -52,15 +70,10 @@ ORIGIN="$(git -C "$ROOT" remote get-url origin)"
 SERVER="$(echo "$ORIGIN" | sed -E 's#(https?://[^/]+)/.*#\1#')"
 REPO="$(echo "${ORIGIN%.git}" | sed -E 's#.*[:/]([^/]+/[^/]+)$#\1#')"
 PROTO="$(sed -n 's/.*protoMax = \([0-9]*\).*/\1/p' "$ROOT/packages/core/lib/src/constants.dart")"
-if [[ -n "$LATEST" && "$LATEST" != "v$VER" ]]; then
-  NOTES="$(git -C "$ROOT" log -n 20 "$LATEST..HEAD" --format='- %s')"
-else
-  NOTES="Starsync $VER."
-fi
 export MANIFEST_FILE="$ROOT/updates/manifest.json" MANIFEST_VER="$VER" \
-  MANIFEST_PROTO="$PROTO" MANIFEST_NOTES="$NOTES" \
+  MANIFEST_PROTO="$PROTO" MANIFEST_CHANGES="$CHANGES" \
   MANIFEST_BASE="$SERVER/$REPO/releases/download/v$VER/starsync-$VER"
-python3 - <<'EOF'
+python3 -I - <<'EOF'
 import json, os
 path = os.environ['MANIFEST_FILE']
 try:
@@ -69,6 +82,7 @@ try:
 except (FileNotFoundError, ValueError):
     manifest = {}
 base = os.environ['MANIFEST_BASE']
+log = json.loads(os.environ['MANIFEST_CHANGES'])
 # Asset names must match tool/package_linux.sh / package_windows.ps1.
 # `url` stays the Linux tarball for builds that predate `assets` (<= 0.2.1).
 assets = {
@@ -80,19 +94,22 @@ manifest.update({
     'protocol': int(os.environ['MANIFEST_PROTO']),
     'url': assets['linux-x64'],
     'assets': assets,
-    'notes': os.environ['MANIFEST_NOTES'].splitlines()[0] if os.environ['MANIFEST_NOTES'] else '',
+    # One line: 1.2.x and 1.3.x apps show only this.
+    'notes': ' '.join(log['notes'].split()) or 'Starsync ' + os.environ['MANIFEST_VER'],
+    # {"added": [...], "changed": [...], "fixed": [...]}: What's new.
+    'changes': log['changes'],
 })
 manifest.pop('sha256', None)
 with open(path, 'w') as f:
-    json.dump(manifest, f, indent=2)
+    json.dump(manifest, f, indent=2, ensure_ascii=False)
     f.write('\n')
 EOF
 
-git -C "$ROOT" add $PUBSPECS updates/manifest.json
+git -C "$ROOT" add $PUBSPECS updates/manifest.json CHANGELOG.md
 if git -C "$ROOT" diff --cached --quiet; then
   echo "everything already at $VER — tagging only"
 else
-  git -C "$ROOT" commit -m "Release v$VER" -- $PUBSPECS updates/manifest.json
+  git -C "$ROOT" commit -m "Release v$VER" -- $PUBSPECS updates/manifest.json CHANGELOG.md
 fi
 git -C "$ROOT" tag -a -m "Release v$VER" "v$VER"
 echo "review with: git show v$VER — then: git push --follow-tags"