From 1b652a4ba2cdd32473409089ee9e06c845115cdb Mon Sep 17 00:00:00 2001 From: DSH Agent Date: Sun, 20 Sep 2026 03:34:01 -0400 Subject: [PATCH] Carry release notes in the tag, verbatim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 40 ++++++++++++++++++++++-------------- README.md | 10 +++++++-- docs/releases/v0.1.3.md | 2 -- 3 files changed, 33 insertions(+), 19 deletions(-) diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index e9462ec..bc938fb 100644 --- a/.gitea/workflows/release.yml +++ b/.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. diff --git a/README.md b/README.md index 615ef26..64875a6 100644 --- a/README.md +++ b/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/.md` when that file exists. +Release notes live in `docs/releases/.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 ``` diff --git a/docs/releases/v0.1.3.md b/docs/releases/v0.1.3.md index 7da4ed0..ec7e6ff 100644 --- a/docs/releases/v0.1.3.md +++ b/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: