Release Notes

Release Notes

Update only the body of the latest existing GitHub Release. Treat the repository diff as the source of truth. Use pull requests and commits only as supporting evidence.

Safety rules

• Use gh for all GitHub Release, pull request, issue, and API operations. Use git fetch only when required tag objects or history are missing.
• Do not create or delete a release.
• Do not change a tag, title, target, draft state, prerelease state, latest-release state, or other release metadata.
• Do not publish a draft.
• Do not use a new release as a fallback when no release exists.
• Do not infer release order from version text, semantic versions, or Git tag order.
• Stop when required evidence is unavailable. Do not publish partial or speculative notes.
• Treat the notes file as a full replacement for the current release body, not as text to append.

1. Verify prerequisites

Run all checks from the repository that the user wants to release:

1. Confirm that the current directory is in a Git worktree:

   git rev-parse --is-inside-work-tree

2. Confirm that gh is available:

   command -v gh

3. Confirm that gh can resolve and access the current GitHub repository. Save its URL and get the GitHub host from it:

   REPO_URL="$(gh repo view --json url --jq '.url')"
   GH_HOSTNAME="${REPO_URL#*://}"
   GH_HOSTNAME="${GH_HOSTNAME%%/*}"

4. Use the repository URL to get its GitHub host. Confirm the active account for that host:

   gh auth status --active --hostname "$GH_HOSTNAME"

Stop with a clear error if a check fails. Do not initialize a Git repository, change authentication, or select another repository as a fallback.

2. Select the release range

Use GitHub's descending release-list order as the release sequence. Include drafts and prereleases because they are existing releases:

gh release list --limit 2 --order desc \
  --json tagName,name,createdAt,publishedAt,isDraft,isPrerelease,isImmutable,isLatest

• Select the first item as the latest release.
• Select the second item as the previous release.
• If the list is empty, stop and state that no existing GitHub Release was found. Never create one.
• If there is one item, treat it as the project's first release.
• Do not re-sort the result. A draft can have no publishedAt value.
• Do not replace either tag with a Git tag that has no GitHub Release.

Set LATEST_TAG and, when present, PREVIOUS_TAG from this result. Quote both values in every command. Then load and record the latest release before any edit:

gh release view \
  --json tagName,name,body,isDraft,isPrerelease,isImmutable,publishedAt,targetCommitish,url \
  -- "$LATEST_TAG"

Confirm that the returned tagName is LATEST_TAG. Record tagName, name, isDraft, isPrerelease, isImmutable, and targetCommitish from this result. Also record isLatest, createdAt, and publishedAt from the release-list result. Use these values for the final safety check. If isImmutable is true, stop and report that GitHub does not permit the body update.

3. Resolve the tag history

Set full Git refs so that a tag that starts with - cannot become a command option:

LATEST_REF="refs/tags/$LATEST_TAG"
PREVIOUS_REF="refs/tags/$PREVIOUS_TAG"

Set PREVIOUS_REF only when PREVIOUS_TAG exists. Confirm that each selected release tag resolves to a local commit:

git rev-parse --verify "$LATEST_REF^{commit}"
git rev-parse --verify "$PREVIOUS_REF^{commit}"

Run the second command only when PREVIOUS_TAG exists. If a tag is missing, inspect the Git remotes, identify the remote for the same GitHub repository, and use git fetch to get the required tags. Do not assume that the remote is named origin. Stop if the remote is ambiguous or a release tag still does not resolve. Do not guess a replacement range.

Check for a shallow repository:

git rev-parse --is-shallow-repository

If the result is true, use the identified GitHub remote to fetch complete history and tags:

git fetch --unshallow --tags "$GITHUB_REMOTE"

Then run the shallow-repository check again. Continue only when the result is false and both required tag commits resolve. If the full history cannot be fetched, stop. Do not generate notes from an incomplete history.

When PREVIOUS_TAG exists, check whether it is an ancestor of LATEST_TAG:

git merge-base --is-ancestor "$PREVIOUS_REF^{commit}" "$LATEST_REF^{commit}"

A non-ancestor result is not an automatic failure. State it in the working notes, use the tree diff to identify the shipped-state change, and inspect both sides of the history so that the commit list does not cause a false claim.

4. Investigate all shipped changes

When a previous release exists, start with:

git log --date=short --format='%H%x09%ad%x09%s' "$PREVIOUS_REF..$LATEST_REF"
git diff --stat "$PREVIOUS_REF" "$LATEST_REF"
git diff --name-status "$PREVIOUS_REF" "$LATEST_REF"
git diff "$PREVIOUS_REF" "$LATEST_REF"

For non-linear history, also inspect:

git log --left-right --graph --oneline "$PREVIOUS_REF...$LATEST_REF"

For the first release, inspect all history reachable from the latest tag and compare its shipped tree with an empty tree:

git log --reverse --date=short --format='%H%x09%ad%x09%s' "$LATEST_REF"
EMPTY_TREE="$(git hash-object -t tree /dev/null)"
git diff --stat "$EMPTY_TREE" "$LATEST_REF"
git diff --name-status "$EMPTY_TREE" "$LATEST_REF"
git diff "$EMPTY_TREE" "$LATEST_REF"

Account for every changed path. Inspect the relevant diff hunks, not only the statistics or file names. For generated or binary files, inspect the source, manifest, configuration, or other evidence that explains their user impact. Do not include working-tree changes or commits after LATEST_TAG.

Use this evidence order:

1. Actual code and configuration diff.
2. Merged pull request title, body, changed files, and linked issue context.
3. Commit messages.

Use PR data when it resolves an unclear purpose, user impact, migration step, or reference. Find associated PRs for a commit when needed:

gh api -H 'Accept: application/vnd.github+json' \
  "repos/{owner}/{repo}/commits/$COMMIT_SHA/pulls"
gh pr view "$PR_NUMBER" \
  --json number,state,mergedAt,title,body,files,commits,closingIssuesReferences,url

Use PR context only when state is MERGED and mergedAt is present. Verify every PR or issue association before adding its number. A commit prefix, PR label, or PR title does not prove user impact.

5. Select user-facing changes

For each changed behavior, identify what a user can observe and the evidence that supports it. Include a change only when it materially affects one or more of these areas:

• behavior or user experience
• compatibility or migration
• installation or configuration
• public commands, flags, APIs, or file formats
• security or privacy
• performance or resource use

Normally exclude refactoring, formatting, lint changes, tests, CI changes, build maintenance, merge commits, routine dependency updates, internal cleanup, and documentation-only changes. Include one only when the diff proves material user impact.

Investigate an ambiguous change before classification. If the available evidence cannot support a useful claim, describe only the supported fact or omit the change. Never invent behavior, fixes, performance results, security effects, breaking effects, migration steps, or PR and issue links.

If no change has material user impact, write only a short, factual summary that says the release contains maintenance changes with no material change to user-visible behavior. Do not create empty sections.