[Bug]: release-notes preview reads the flip-utils version, and its changelog never generates

[atriaybagur]

Description

The release-notes preview posted on every develop → main PR announced the wrong version, and its
changelog section had never rendered. Two independent faults, both in
.github/workflows/pr-release-notes-preview.yml, both pre-existing. Found while writing up #924.

1 — It previewed flip-utils, not the platform release

The workflow read the flip-utils package version; release.yml — which actually mints the tag — reads the
root manifest:

# pr-release-notes-preview.yml (before)         → 0.4.1
VERSION=$(grep -m1 '__version__' flip-utils/flip/__init__.py | sed 's/.*= *"\(.*\)"/\1/')

# release.yml:42 (the tag that gets created)    → 0.4.0
VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/version = "\(.*\)"/\1/')

flip-utils ships to PyPI as flip and is versioned independently of the platform
(CONTRIBUTING → Versioning), so the preview was describing a
different artefact than the one being released. Both recent release PRs were wrong:

Release PR	Preview announced	Actually tagged
#924	flip v0.4.1	v0.4.0
#808	flip v0.4.0	v0.3.0

It escaped notice until now because the two numbers happened to look plausible; #917 split them apart and made
the mismatch obvious. The lowercase flip in the comment heading against the FLIP in
RELEASE_NOTES_TEMPLATE.md is the same package-vs-platform conflation, so the heading is corrected too.

2 — The changelog never generated

generateReleaseNotes API error: Resource not accessible by integration

POST /repos/{owner}/{repo}/releases/generate-notes requires contents: write; the workflow granted
contents: read. Every call failed, the catch swallowed it, and the comment rendered the bare template with
"Could not generate changelog preview at this time." in place of the changelog — so "PRs merged in this
release" and "Acknowledgements" have never populated. That is the preview's entire purpose.

Fixed by overriding to contents: write at the job level and leaving the workflow default read-only —
the same shape release.yml already uses for tag creation.

On the permission bump

This is a pull_request trigger, not pull_request_target, so a fork PR gets a read-only GITHUB_TOKEN
regardless of the permissions: block. The write token therefore only exists for a same-repo branch, and the
job is additionally gated on head.ref == 'develop'. The job runs no untrusted input through a shell: the only
event data reaching run: is head.sha, which is hex-constrained.

3 — Why it survived two releases

The fallback text read as an empty release rather than a broken workflow, so nobody chased it. The error is
now reported through core.warning (a run annotation) and inlined into the comment as a > [!WARNING] block
naming the actual API message, so the next failure says what broke rather than shrugging.

Linked Issues

Fixes #925

Checklist

• Follows the project's coding conventions and style guide
• Updates documentation — n/a, no user-facing or documented behaviour changes
• I have added tests that prove my fix is effective or that my feature works — n/a, see Testing below
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Type of Change

• Non-breaking change (fix or new feature that would not break existing functionality).
• Breaking change (fix or new feature that would cause existing functionality to change).
• New tests added to cover the changes.
• In-line docstrings updated.
• Documentation updated, tested make -C docs/ docs.

Testing

This workflow only fires on pull_request → main with head.ref == 'develop', so it cannot execute on this
PR. Verified by direct equivalence and static checks instead:

• Version extraction matches release.yml byte-for-byte. Running the new command against the current root
  manifest yields VERSION=0.4.0 / TAG=v0.4.0 — identical to release.yml's output, and the version develop -> main #924
  will actually tag. The old command yields 0.4.1.
• Previous-tag resolution unchanged: git tag --list 'v*.*.*' | sort -V | tail -n1 → v0.3.0.
• Workflow parses as valid YAML; job-level permissions resolves to {contents: write, pull-requests: write} with the workflow default still {contents: read, pull-requests: write}.
• The embedded github-script body passes node --check.
• The contents: write fix cannot be proven short of a real develop → main PR — the next release PR is the
  first live exercise. The failure mode if it is still wrong is unchanged from today (a warning block instead
  of a populated changelog), and it cannot affect the release itself.

Additional Notes

Not a blocker for #924, and not fixable within it. The preview is a PR comment only; release.yml reads
the correct source and will tag v0.4.0 either way. This lands on develop after #924 merges, so the
corrected preview first appears on the next release PR. #924's description carries a note telling reviewers
to ignore the v0.4.1 in its own preview comment.

Follow-up filed as #927 — the shared v* tag namespace between platform and flip-utils releases (see Known limitation below).

Separate, not addressed here: the changelog categories in
.github/release.yml key off labels feature, fix, docs, ci,
build, chore — none of which exist in this repo's label set (only bug, documentation, enhancement
and dependencies overlap). Once the changelog actually generates, most PRs will land under "Other Changes"
until the labels are reconciled. Worth its own issue.

Known limitation: this does not resolve the shared tag namespace

release.yml (platform, root pyproject.toml) and release-pypi.yml (flip-utils, flip.__version__) both
mint v<version> tags and GitHub Releases into the same v* namespace, on the same push to main, for two
independently-versioned artefacts. This PR corrects which version the preview names; it does not touch that
collision. Two consequences worth knowing before merging:

• PREV_TAG stays cross-contaminated. git tag --list 'v*.*.*' | sort -V | tail -n1 takes the highest tag
  across both artefacts, so once flip-utils starts tagging, a FLIP release PR can compare against a flip-utils
  tag on an unrelated commit. Left as-is here deliberately — fixing it properly means separating the
  namespaces, not special-casing the glob. The same line exists at release-pypi.yml:120. Tracked in [Bug]: platform and flip-utils releases share one v* tag namespace and will silently suppress each other #927.
• The preview covers the platform release only. A push to main can cut two releases; this comment
  describes one. Whether it should grow a second flip-utils section is a design question for the namespace
  work, not this fix.

Neither is a regression: today the preview is wrong about the platform version and has no changelog at all.

Why nothing has collided yet: release-pypi.yml has never completed a run, so all five existing v* tags
are release.yml's. Its tag step also runs after the PyPI publish, so the current 422 invalid-publisher
failure aborts before tagging. The collision arms itself the moment trusted publishing is configured — which
makes the namespace split worth doing before that, not after.

Acceptance Criteria

Imported from issue #925

• The preview comment on a develop → main PR announces the version from the root pyproject.toml —
  the same value release.yml uses to create the tag.
• The preview's changelog section contains the generated changelog (categorised per
  .github/release.yml), not
  _Could not generate changelog preview at this time._. (Implemented; first live exercise is the next
  release PR — see Testing.)
• contents: write is scoped to the job, not the workflow, matching the pattern in release.yml.
• The preview heading names the platform (FLIP), not the PyPI package (flip), consistent with
  RELEASE_NOTES_TEMPLATE.md.

[github-actions]

✅ Acceptance criteria have been automatically imported from the linked issue(s) and added to the PR description.

[github-actions]

✅ Acceptance criteria have been automatically imported from the linked issue(s) and added to the PR description.