docs: require human release notes

release-notes/v0.1.0-alpha.3.md

@@ -0,0 +1,5 @@
+## Highlights
+
+- Client-facing errors no longer expose internal server details.
+- The SMTP security selector follows the rest of the server settings UI.
+- The release workflow uploads only artifacts belonging to the requested version and marks alpha versions as prereleases.

scripts/publish-github-release.sh

@@ -6,6 +6,7 @@ VERSION="${1:-}"
 REPOSITORY="mirivlad/verstak-sync-server"
 RELEASE_SCRIPT="${VERSTAK_RELEASE_SCRIPT:-$ROOT/scripts/release.sh}"
 RELEASE_DIR="${VERSTAK_RELEASE_DIR:-$ROOT/release}"
+RELEASE_NOTES_DIR="${VERSTAK_RELEASE_NOTES_DIR:-$ROOT/release-notes}"
 GIT_BIN="${GIT_BIN:-git}"
 GH_BIN="${GH_BIN:-gh}"
 
@@ -62,7 +63,17 @@ fi
 if "$GH_BIN" release view "$VERSION" --repo "$REPOSITORY" >/dev/null 2>&1; then
   "$GH_BIN" release upload "$VERSION" "${ASSETS[@]}" --repo "$REPOSITORY" --clobber
 else
-  RELEASE_OPTIONS=(--generate-notes --verify-tag)
+  NOTES_FILE="$RELEASE_NOTES_DIR/$VERSION.md"
+  if [[ ! -s "$NOTES_FILE" ]]; then
+    echo "human-readable release notes are required: $NOTES_FILE" >&2
+    exit 1
+  fi
+
+  RELEASE_OPTIONS=(--notes-file "$NOTES_FILE" --generate-notes --verify-tag)
+  PREVIOUS_TAG="$("$GIT_BIN" describe --tags --abbrev=0 "${HEAD}^" 2>/dev/null || true)"
+  if [[ -n "$PREVIOUS_TAG" ]]; then
+    RELEASE_OPTIONS+=(--notes-start-tag "$PREVIOUS_TAG")
+  fi
   if [[ "$VERSION" == *-* ]]; then
     RELEASE_OPTIONS+=(--prerelease)
   else

scripts/test-publish-github-release.sh

@@ -15,9 +15,10 @@ if [[ ! -x "$PUBLISHER" ]]; then
   exit 1
 fi
 
-mkdir -p "$WORK/bin" "$WORK/release" "$WORK/state"
+mkdir -p "$WORK/bin" "$WORK/release" "$WORK/release-notes" "$WORK/state"
 LOG="$WORK/log"
 export LOG
+printf '## Highlights\n\nHuman-readable release notes.\n' > "$WORK/release-notes/$VERSION.md"
 
 cat > "$WORK/release.sh" <<'SCRIPT'
 #!/usr/bin/env bash
@@ -48,6 +49,7 @@ case "${1:-}" in
     fi
     echo test-commit
     ;;
+  describe) echo v0.0.0-previous ;;
   tag) touch "$TEST_STATE/tag"; printf 'tag:%s\n' "${3:-}" >> "$LOG" ;;
   push) printf 'push:%s:%s\n' "${2:-}" "${3:-}" >> "$LOG" ;;
   *) echo "unexpected git invocation: $*" >&2; exit 1 ;;
@@ -73,6 +75,7 @@ chmod +x "$WORK/bin/gh"
 run_publisher() {
   VERSTAK_RELEASE_SCRIPT="$WORK/release.sh" \
   VERSTAK_RELEASE_DIR="$WORK/release" \
+  VERSTAK_RELEASE_NOTES_DIR="$WORK/release-notes" \
   GIT_BIN="$WORK/bin/git" \
   GH_BIN="$WORK/bin/gh" \
   EXPECTED_ROOT="$ROOT" \
@@ -87,6 +90,9 @@ grep -Fqx "push:origin:refs/tags/$VERSION" "$LOG"
 grep -F "release create $VERSION" "$LOG" >/dev/null
 grep -F "$ASSET_NAME" "$LOG" >/dev/null
 grep -F "SHA256SUMS" "$LOG" >/dev/null
+grep -F -- "--notes-file $WORK/release-notes/$VERSION.md" "$LOG" >/dev/null
+grep -F -- "--generate-notes" "$LOG" >/dev/null
+grep -F -- "--notes-start-tag v0.0.0-previous" "$LOG" >/dev/null
 grep -F -- "--prerelease" "$LOG" >/dev/null
 if grep -F -- "--latest" "$LOG" >/dev/null; then
   echo "alpha release was incorrectly marked latest" >&2