chore(release): require curated release notes

docs/RELEASE_NOTES_BACKLOG.md

@@ -0,0 +1,15 @@
+# Release Notes Backlog
+
+## Next Release Required Work
+
+- Backfill missing or thin historical release notes before cutting the next release.
+- Audit every `CHANGELOG.md` section from `v1.7.44-alpha` through the current release.
+- Replace raw commit-hash entries with user/operator-facing bullets that explain behavior changes, operational impact, validation, and known limitations.
+- Ensure `releases/manifest.json` changelog entries come from curated `CHANGELOG.md` notes only.
+
+## Release Note Policy
+
+- Every release must have at least three curated bullets.
+- Raw `git log --oneline` output is not acceptable release documentation.
+- Notes should answer what changed, why it matters, what operators should expect, and any known limitations.
+- `scripts/check-release-manifest.sh` is the enforcement gate before publishing artifacts.

scripts/check-release-manifest.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # Validate releases/manifest.json:
 #   - version matches core/archipelago/Cargo.toml
-#   - changelog is non-empty (release notes are mandatory per product policy)
+#   - changelog contains curated release notes, not raw git log output
 #   - every component's download_url exists on disk and matches sha256/size
 #
 # Run on every push from CI, and also locally before publishing a release:
@@ -30,12 +30,42 @@ if [ "$MANIFEST_VERSION" != "$CARGO_VERSION" ]; then
 fi
 ok "version matches: $MANIFEST_VERSION"
 
-# Release notes mandatory — ships stuff nobody can read otherwise.
+# Release notes mandatory — ships stuff nobody can read otherwise. Require
-CHANGELOG_COUNT=$(python3 -c "import json; print(len(json.load(open('$MANIFEST'))['changelog']))")
+# curated user/operator-facing notes and reject raw `git log --oneline` output.
-if [ "$CHANGELOG_COUNT" -eq 0 ]; then
+NOTES_CHECK=$(python3 - "$MANIFEST" <<'PY'
-    fail "changelog is empty — every release MUST have release notes"
+import json
-fi
+import re
-ok "changelog has $CHANGELOG_COUNT lines"
+import sys
+
+manifest = sys.argv[1]
+notes = json.load(open(manifest)).get("changelog", [])
+if len(notes) < 3:
+    print(f"FAIL: changelog has {len(notes)} lines; need at least 3 curated release-note bullets")
+    sys.exit(0)
+
+bad = []
+for note in notes:
+    text = str(note).strip()
+    if not text:
+        bad.append("empty release-note entry")
+    if len(text) < 40:
+        bad.append(f"too short: {text!r}")
+    if re.match(r"^[0-9a-f]{7,40}\s+", text):
+        bad.append(f"raw commit hash entry: {text!r}")
+    if re.match(r"^(feat|fix|chore|docs|test|refactor|build|ci|perf)(\([^)]+\))?:\s", text):
+        bad.append(f"raw conventional-commit entry: {text!r}")
+
+if bad:
+    print("FAIL: release notes must be curated user/operator-facing bullets, not raw git log lines:\n" + "\n".join(bad))
+else:
+    print(f"OK: changelog has {len(notes)} curated lines")
+PY
+)
+case "$NOTES_CHECK" in
+    OK:*) ok "${NOTES_CHECK#OK: }" ;;
+    FAIL:*) fail "${NOTES_CHECK#FAIL: }" ;;
+    *) fail "unexpected release-note validation output: $NOTES_CHECK" ;;
+esac
 
 # Each component: the artifact on disk under releases/v<version>/ must match
 # the declared sha256 and size_bytes.

scripts/create-release.sh

@@ -128,36 +128,20 @@ cd "$PROJECT_ROOT/neode-ui"
 npm run build 2>&1 | tail -3
 cd "$PROJECT_ROOT"
 
-echo "[4/7] Generating changelog..."
+echo "[4/7] Validating curated changelog..."
-# Get commits since last tag (or last 50 if no tags)
-LAST_TAG=$(git -C "$PROJECT_ROOT" describe --tags --abbrev=0 2>/dev/null || echo "")
-if [ -n "$LAST_TAG" ]; then
-    GIT_LOG=$(git -C "$PROJECT_ROOT" log "$LAST_TAG"..HEAD --oneline --no-merges 2>/dev/null || echo "")
-else
-    GIT_LOG=$(git -C "$PROJECT_ROOT" log --oneline --no-merges -50 2>/dev/null || echo "")
-fi
 
-# Create/update CHANGELOG.md entry
 CHANGELOG_FILE="$PROJECT_ROOT/CHANGELOG.md"
 RELEASE_DATE=$(date +%Y-%m-%d)
-CHANGELOG_ENTRY="## v${VERSION} (${RELEASE_DATE})
+if [ ! -f "$CHANGELOG_FILE" ] || ! grep -q "^## v${VERSION} (" "$CHANGELOG_FILE"; then
-
+    echo "Error: CHANGELOG.md must already contain curated notes for v${VERSION}."
-$GIT_LOG
+    echo "Add a section like:"
-"
+    echo ""
-
+    echo "## v${VERSION} (${RELEASE_DATE})"
-if [ -f "$CHANGELOG_FILE" ]; then
+    echo ""
-    # Prepend new entry after the first line (title)
+    echo "- User/operator-facing change ..."
-    EXISTING=$(cat "$CHANGELOG_FILE")
+    echo "- Another concrete change ..."
-    FIRST_LINE=$(head -1 "$CHANGELOG_FILE")
+    echo "- Validation or operational note ..."
-    REST=$(tail -n +2 "$CHANGELOG_FILE")
+    exit 1
-    echo "$FIRST_LINE" > "$CHANGELOG_FILE"
-    echo "" >> "$CHANGELOG_FILE"
-    echo "$CHANGELOG_ENTRY" >> "$CHANGELOG_FILE"
-    echo "$REST" >> "$CHANGELOG_FILE"
-else
-    echo "# Changelog" > "$CHANGELOG_FILE"
-    echo "" >> "$CHANGELOG_FILE"
-    echo "$CHANGELOG_ENTRY" >> "$CHANGELOG_FILE"
 fi
 
 echo "[5/7] Creating release manifest..."