release-fetch-changelog

name	release-fetch-changelog
description	Calls the GitHub REST API via `gh` to generate release notes for the given tag (the same content the "Generate release notes" button produces on the web UI) and inserts the result into the matching CHANGELOG-X.Y.md file. Used standalone or by the /release orchestrator when UpdateChangelogReleaseWorker is up next.
user_invocable	true
version	2.0.0

release-fetch-changelog

Automates the GitHub "Generate release notes" copy-paste step using the gh CLI. The GitHub-native generator stays the source of truth — this skill does not draft the changelog body itself.

Invocation

/release-fetch-changelog <version> --target-branch <branch> [--changelog-file <path>] [--dry-run]

• <version> — e.g. v19.1.0, v19.0.1-rc1.
• --target-branch <branch> — e.g. 19.0. Required.
• --changelog-file <path> — override the conventional location CHANGELOG-<major>.<minor>.md at repo root.
• --dry-run — fetch + show the generated markdown but do not write.

Pre-flight

Abort with a clear error if any fail:

1. gh auth status succeeds.
2. The CHANGELOG file exists at the resolved path. If not, ask the operator to confirm the path with --changelog-file.
3. gh release view <version> returns "release not found" — bail out if the tag/release already exists.

Steps

1. Find previous tag. Pick the highest version-sorted tag strictly less than <version>, not the most-recently-published one. Shopsys maintains older majors as LTS lines (e.g. v14.5.1 was published after v18.0.0), so sorting by publishedAt would compare a new major against an older LTS patch and produce a misleading diff. Inject <version> into the tag list, sort, and print the entry immediately above it (substitute <version> with the actual version literal — leaving the placeholder string in place will produce no output because it fails the semver regex):

   { echo "<version>"; gh api repos/shopsys/shopsys/tags --paginate --jq '.[].name'; } \
       | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
       | sort -V -u \
       | awk -v t="<version>" '$0 == t { print prev; exit } { prev = $0 }'
   

   sort -V already orders semver tags ascending, so awk just walks the list and prints the line right before <version>. The echo "<version>" injection makes this work whether or not <version> is already in the tag list. For v19.0.0, this returns v18.0.0, not v14.5.1. This is what GitHub's generator uses as the comparison baseline.
2. Generate notes via gh. Call:

   gh api repos/shopsys/shopsys/releases/generate-notes \
       -f tag_name=<version> \
       -f previous_tag_name=<previous-tag> \
       -f target_commitish=<branch> \
       --jq .body
   

   This returns the same markdown the "Generate release notes" button produces on https://github.com/shopsys/shopsys/releases/new.
3. Read the CHANGELOG. Find the first existing ## v heading. New content goes immediately above it. If no such heading exists, insert just after the line <!-- Add generated changelog below this line --> (the convention used by CHANGELOG-X.Y.md headers); if neither exists, prepend to the top.
4. Build the inserted block. A ## [<version>](https://github.com/shopsys/shopsys/compare/<previous-tag>...<version>) (YYYY-MM-DD) heading (today's date) + a blank line + the generated markdown + a trailing blank line. The bracketed/linked heading form is required — CheckChangelogForTodaysDateReleaseWorker matches the regex #\#\# \[<version>\]\(.*\) \(\d+-\d+-\d+\)# and fails out of the release stage if the heading is a plain ## <version> (date).
5. Write. Update the CHANGELOG file. Do not run git add or commit — UpdateChangelogReleaseWorker runs phing markdown-fix and commits afterwards.
6. Report. Print:
   • Inserted heading.
   • First 3 lines of the generated body.
   • Byte count.
   • Path written.

On --dry-run, do steps 1-2 and print what would be inserted, then exit without writing.

Failure handling

• gh api error / non-2xx response → leave the CHANGELOG untouched, print the response body, instruct the operator to open https://github.com/shopsys/shopsys/releases/new?tag=<version>&target=<branch> manually and paste themselves. The /release orchestrator should detect this exit code and fall back to a regular surface-the-prompt flow.
• gh not authenticated → tell the operator to run gh auth login. Do not attempt to authenticate for them.
• Generated markdown is empty (no PRs between tags) → write _No changes since previous tag._ as the body and print a warning so the operator can double-check.

Constraints

• Never commit, push, or tag.
• Never edit any file other than the resolved CHANGELOG path.
• Never post to GitHub on the operator's behalf — releases/generate-notes is a read-only generator endpoint; do not switch to POST /releases or any other write endpoint.