release-docs: prepare-publish bases publish commit on stale branch tip, dropping LFS .gitattributes

[kojiromike]

Problem

The release-docs.yml workflow can publish the b10 SchemaSpy tree as raw file content instead of git-lfs pointers, defeating the git-lfs design from #139 and bloating the Hugo repo. Observed on the retroactive 8.1.0 production run: PR #129 contained +1,040,333 lines across 891 files (raw HTML + vendored bower assets) rather than ~3-line LFS pointers.

Root cause

tools/release-docs/Taskfile.yml → workflow:prepare-publish bases the publish commit on the existing remote branch tip:

if git -C "$PUBLISH" fetch ... "+refs/heads/${BRANCH}:refs/remotes/origin/${BRANCH}"; then
  git -C "$PUBLISH" checkout -B "$BRANCH" "origin/${BRANCH}"   # <-- swaps working tree to old branch content
else
  git -C "$PUBLISH" checkout -B "$BRANCH"                       # fresh from master clone
fi

The depth-1 clone is of master (which has the static/documentation/*/b10/** filter=lfs rule in .gitattributes). But when origin/$BRANCH already exists, checkout -B "$BRANCH" origin/$BRANCH switches the working tree to that branch's content. For release-docs/8.1.0 — created 2026-05-27, before the .gitattributes rule landed in #139 — the branch has no .gitattributes, so the LFS clean filter never matches and the tree commits as raw content. Every subsequent dispatch inherits the missing attribute and keeps storing raw content.

The test branch (release-docs-test/8.1.0) is unaffected only because it never existed before #139 and so always took the fresh-from-master path.

Impact

• Any release-docs/<v> branch created before the .gitattributes rule will publish raw content if re-dispatched (latent on release-docs/8.1.6, release-docs/8.1.7).
• More generally, future changes to .gitattributes on master won't propagate to existing publish branches.

Suggested fix

Base the publish branch on origin/master each dispatch (e.g. checkout -B "$BRANCH" origin/master) so it always carries master's .gitattributes, rather than accumulating on the stale branch tip. (update-manifest already mutates $PUBLISH/data/releases.json, which would then come from master's live manifest — the desired source anyway.) Alternatively, explicitly restore .gitattributes from master before git add.

Workaround applied for 8.1.0

Deleted the stale release-docs/8.1.0 branch (auto-closed PR #129) and re-dispatched, forcing the fresh-from-master path.

[kojiromike]

Related second bug in the same task: upsert-pr matches closed PRs

While remediating 8.1.0 (delete stale branch + re-dispatch), the re-dispatch ran green and workflow:upsert-pr reported success, but no open PR was created. Cause:

if gh pr view "$BRANCH" --repo "$GITHUB_REPOSITORY" --json number >/dev/null 2>&1; then
  gh pr edit "$BRANCH" ...      # <-- ran against the CLOSED PR #129
else
  gh pr create --draft ...
fi

gh pr view "$BRANCH" resolves to the most recent PR for the head including closed ones. After a branch is deleted+recreated (which closes its old PR), the check matches the dead PR and the task runs gh pr edit on it (editing a closed PR's title/body) instead of creating a fresh one. Result: corrected branch content, but no open PR. Had to create #142 manually.

Suggested fix

Scope the existence check to open PRs, e.g.:

num=$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$BRANCH" --state open --json number --jq '.[0].number')
if [ -n "$num" ]; then gh pr edit "$num" ...; else gh pr create --draft ...; fi

Both this and the .gitattributes/branch-base issue live in tools/release-docs/Taskfile.yml (workflow:prepare-publish / workflow:upsert-pr) and are best fixed together.