Repository navigation
docs(release): correct stale troubleshooting guidance and the incomplete finalize summary #3485
Description
Problem
docs/release.md carries two claims about pull-requests-release.yaml that no longer match the workflow, and the first one actively misdirects a maintainer during a release.
The troubleshooting table at line 560 attributes Draft release for vX.Y.Z not found to the Publish draft release step having lost its github-token in a past refactor, and sends the reader to pull-requests-release.yaml:163. The release checklist at line 552 repeats the claim and blames refactor 66a756b6. That guidance was accurate when it was written, but the token was restored in 7d2fe2f7d on 2026-04-29 and the docs never caught up. On current main the step sits at line 234 and carries github-token: ${{ steps.app-token.outputs.token }} at line 238, so the diagnosis and the line reference are both wrong, and line 163 is a different step. A maintainer who hits that symptom on release day is pointed at a regression fixed three months ago and away from whatever is actually failing.
Separately, the tag-immutability table at line 577 summarises what the workflow mutates: the stable tag, the Go-module tag, the maintenance branch and the image retag. It never mentions publishing the cozy-installer chart. That row is what a reader consults to answer "what does this workflow actually write", and the chart is one of the two registry artifacts it produces, so the summary reads as complete while being short by one.
I found both while reviewing #3456, which moves the registry steps into a separate job. Neither is caused by that change and neither belongs in it, so I am filing them on their own.
Proposed change
Replace the troubleshooting row and the checklist bullet with guidance that matches the workflow as it stands. If Draft release for vX.Y.Z not found is still reachable, describe the cause that can still produce it: the draft is orphaned when a tag is deleted and recreated between draft creation and merge, which the step already detects by matching on release name and repairing tag_name. If it is no longer reachable at all, drop the entry instead of leaving a fixed bug documented as current.
Drop the hardcoded line number while doing it. A line reference into a workflow this active goes stale on the next edit, and naming the step is enough to locate it.
Add the chart publish to the tag-immutability row so the summary covers both registry artifacts the workflow writes.
Activity