Skip to content

docs(release): correct stale troubleshooting guidance and the incomplete finalize summary #3485

Open

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

  1. added
    kind/documentationCategorizes issue or PR as related to documentation
    area/releaseIssues or PRs related to release tooling (changelog, backport, release pipeline)
    on Jul 29, 2026
  2. added
    triage/acceptedIndicates an issue is ready to be actively worked on
    priority/backlogGeneral backlog priority. Lower than priority/important-longterm
    and removed
    triage/needs-triageIndicates an issue needs triage by a maintainer
    on Sep 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/releaseIssues or PRs related to release tooling (changelog, backport, release pipeline)kind/documentationCategorizes issue or PR as related to documentationpriority/backlogGeneral backlog priority. Lower than priority/important-longtermtriage/acceptedIndicates an issue is ready to be actively worked on

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions