Carry release notes in the tag, verbatim

The notes now travel in the tag annotation, which is the one thing the runner
provably receives — it is named in the fetch refspec. Fetching them from the
worktree failed three different ways in five runs: `[ -f ]` false, `cat` empty,
and then `git show HEAD:` empty because the shallow fetch had not brought the
blob across. v0.1.3 shipped a placeholder body each time.

Two details that each silently ate the notes on the way here:

  * `git tag -a -F` runs its default cleanup, which treats every line starting
    with `#` as a comment. These notes are mostly headings, so most of the
    document disappeared. `--cleanup=verbatim` is now required when tagging,
    and the README shows the exact commands.
  * `%(contents:body)` applies the same comment-stripping. The workflow reads
    `%(contents)` and drops the subject line instead.

Verified with a round-trip against a scratch repo: tag message in, byte-exact
notes out. The leading H2 is gone from the file, since the release title
already carries it.

.gitea/workflows/release.yml

@@ -185,33 +185,43 @@ jobs:
           echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
           echo "pushed ${{ steps.version.outputs.ref }}:${{ steps.version.outputs.version }} @ ${DIGEST}"
 
-      # Read the release notes out of git rather than the working tree.
+      # Read the release notes from the tag object itself.
       #
-      # This is not paranoia. Across four runs of this workflow, act_runner
-      # produced a worktree where `git ls-files docs` listed
-      # docs/releases/v0.1.3.md, `ls docs/releases` showed the directory, and
-      # the file itself was simply absent — intermittently, from the same
-      # commit. The v0.1.3 release went out with a placeholder body twice
-      # because of it, and the probes that diagnosed it are in the history.
+      # This is not paranoia about the notes file. Across five runs of this
+      # workflow, act_runner produced worktrees where `git ls-files docs` and
+      # `ls docs/releases` both showed docs/releases/v0.1.3.md while the file
+      # itself was absent — intermittently, from the same commit — and then
+      # `git show HEAD:...` came back empty too, because the shallow fetch had
+      # not brought that blob across. Three separate ways of reading one file
+      # failed for three different reasons, and v0.1.3 shipped a placeholder
+      # body three times because of it.
       #
-      # `git show` reads the blob from the object database, so it does not care
-      # what the checkout raced on. Combined with `|-` on the command
-      # substitution, a genuinely missing notes file still falls back cleanly
-      # instead of taking the release down with it.
+      # The tag object is the one thing the runner provably receives: it is
+      # named in the fetch refspec itself. So the notes live there, written at
+      # tag time with `git tag -a v0.1.4 -F docs/releases/v0.1.4.md`. The docs
+      # file stays as the thing a human edits and reads on the web.
       - name: Collect release notes
         if: github.ref_type == 'tag'
         run: |
           set -u
+          TAG="${{ github.ref_name }}"
           VERSION=$(grep -m1 '^version' Cargo.toml | sed 's/.*"\(.*\)".*/\1/')
-          NOTES=$(git show "HEAD:docs/releases/${VERSION}.md" 2>/dev/null || true)
+
+          # Everything after the tag's subject line, with the blank line that
+          # separates them dropped. `%(contents:body)` is not used here: it
+          # also treats any line starting with `#` as a comment, which silently
+          # removed every heading from these notes.
+          NOTES=$(git tag -l --format='%(contents)' "$TAG" 2>/dev/null | tail -n +2 | sed '/./,$!d' || true)
+          if [ -z "$NOTES" ]; then
+            NOTES=$(git show "HEAD:docs/releases/${VERSION}.md" 2>/dev/null || true)
+          fi
           if [ -n "$NOTES" ]; then
-            echo "notes: docs/releases/${VERSION}.md (${#NOTES} bytes, from git)"
+            echo "notes: ${#NOTES} bytes from tag ${TAG}"
           else
             NOTES=$(printf 'Release %s.\n\nSee the repository README for deployment instructions.' "$VERSION")
-            echo "::warning::no docs/releases/${VERSION}.md in this commit; using a placeholder"
+            echo "::warning::tag ${TAG} has no notes body; using a placeholder"
           fi
           printf '%s' "$NOTES" > /tmp/notes.md
-          echo "collected ${#NOTES} bytes of release notes"
 
       # Releases are created only for tags. A main-branch rebuild ships the same
       # version again and must not rewrite the notes of an existing release.

README.md

@@ -200,13 +200,19 @@ registry yet is worse than no release, and a broken build must not overwrite a
 tag that already works. The workflow also asserts the tag and `Cargo.toml`
 agree, which is what catches a tag pushed without a version bump.
 
-Release notes come from `docs/releases/<version>.md` when that file exists.
+Release notes live in `docs/releases/<version>.md` and are carried into the
+release through the tag annotation, which is the one thing the runner provably
+receives — Gitea's shallow checkout has intermittently omitted files from the
+worktree. So tag with `--cleanup=verbatim`, which stops git treating every `#`
+line in the notes as a comment:
 
 ```bash
 # cut a release
 sed -i 's/^version = "0.1.3"/version = "0.1.4"/' Cargo.toml   # and Cargo.lock
 git commit -am "v0.1.4: ..."
-git tag -a v0.1.4 -m "v0.1.4: ..."
+NOTES=docs/releases/v0.1.4.md
+{ echo "v0.1.4: one-line summary"; echo; cat "$NOTES"; } > /tmp/tagmsg
+git tag -a v0.1.4 -F /tmp/tagmsg --cleanup=verbatim
 git push origin main v0.1.4
 ```
 

docs/releases/v0.1.3.md

@@ -1,5 +1,3 @@
-## The vault can no longer be destroyed by a crash
-
 This release fixes the failure that could leave the container in a restart loop
 with: