generate-release-notes

name

generate-release-notes

description

Generate a redis-py GitHub release-notes draft and save it as a Markdown file. Collects the merged PRs/commits since the previous release, maps each commit to its PR labels, categorizes them into the project's release sections (Breaking Changes, Deprecations, Experimental Features, New Features, Bug Fixes, Maintenance) using the skill's pr-labels-guide, infers a category for unlabeled PRs, and assembles the notes with an optional Highlights section and a contributors footer. Trigger this skill whenever the user says "release notes", "create release notes", "generate release notes", "draft release notes", "prepare release notes", "changelog", or asks for the release notes/changelog of a specific version or branch (e.g. "release notes for 8.0", "generate release notes for the 8.0 branch", "what changed since the last release"). A phrase like "release notes for 8.0" means: use branch `8.0` as the release-branch input. Also use when asked to summarize what changed since the last tag.

Generate Release Notes

Objective

Produce a redis-py release-notes draft that matches the structure of the project's published GitHub releases, derived from the merged PRs on a given release branch since the previous release and categorized by PR label. The release branch is the skill's primary input (step 1). Save the result as a Markdown file. Never publish it — drafting only; the user publishes the release themselves.

Do not rely on any automated release-drafter output. We do not use it to decide which PRs are included or how they are categorized — it misses PRs and miscategorizes them. Collect the PRs yourself from the git history (step 2) and categorize every one of them manually using this skill's references, which are the complete and authoritative rules:

• references/release-notes-template.md — the section order, titles, line format, and full skeleton.
• references/pr-labels-guide.md — the authoritative label→category mapping, what each label means, and how to categorize a PR/commit that has no category label.

Constraints

• Read-only GitHub access only. Per the repository owner's standing rule, never run gh (or any GitHub API call) that writes — no creating/editing releases, comments, labels, or tags — unless the user explicitly authorizes that specific action in the same turn. Use gh ... view/list, git log, or GET-only gh api/curl to gather data. gh may fail with a TLS error inside the command sandbox; run it with the sandbox disabled when needed.
• This skill only writes the draft Markdown file in the working tree. It does not commit, tag, push, or create a GitHub release.

Workflow

1. Determine the release range and version

1. Read the release branch as input. The branch the release is cut from is the primary input to this skill — it defines which changes are included. Take it from the skill invocation/args if provided; otherwise ask the user for it (e.g. 8.0, release/8.0.2, master). Do not guess. Verify it exists (git rev-parse --verify <branch>; fetch first if it is a remote branch, origin/<branch>). Every change to include is a commit reachable from this branch and not from the previous release tag.
2. Identify the previous release tag: the most recent v* tag reachable from the release branch, git describe --tags --abbrev=0 <branch> (or gh release list -L 5, read-only). Confirm with the user if a non-default base is intended.
3. Decide the new version. redis-py ships major, minor, and patch releases (e.g. 8.0.1, 7.4.1). Infer minor vs patch from the change set (any Breaking/New Feature → at least a minor bump) and confirm the exact version with the user if unclear. The tag form is v<version>.

2. Collect the merged PRs / commits in range

1. List the commits on the release branch since the previous tag: git log --oneline --no-merges <prev-tag>..<branch>. Each squashed/merged commit title typically ends with (#<pr-number>); extract that number. For merge-commit workflows, use git log --merges or the GitHub compare API instead.
2. For each PR number, fetch its title, labels, and author (read-only): gh pr view <n> --json number,title,labels,author or gh api repos/redis/redis-py/pulls/<n>. Use the PR title for the change line (it is what the published notes use), not the raw commit subject, when they differ.
3. Drop any PR labeled skip-changelog.
4. If a commit has no associated PR (direct push), use the commit subject and treat it as unlabeled.

3. Categorize each commit

For each remaining commit, categorize it using references/release-notes-template.md and references/pr-labels-guide.md:

• If the PR has one or more category labels, list it under every matching section — a PR with two category labels appears in both (e.g. deprecation + breakingchange → both ⚠️ Deprecations and 🔥 Breaking Changes).
• If the PR has no category label, or only topic/process labels, or a non-category repo label (e.g. bug-fix, security, techdebt), infer the section(s) using references/pr-labels-guide.md — apply every inference rule that matches, so a change may land in more than one section. Note the inferred labels you would suggest applying to the PR.
• When a category is genuinely ambiguous, place your best guess and leave a <!-- TODO: confirm category for #<n> --> marker, then surface it to the user.

4. Assemble the draft

Follow references/release-notes-template.md:

1. Start with # Changes.
2. Optionally add ## ✨ Highlights (or a lead prose paragraph) — hand-authored ### subsections describing each highlight with API names and doc/spec links. Include it only when the release has something significant to focus the reader on: a notable new feature, or a breaking change that may affect a large share of users. Omit for routine patch releases. When the release contains Breaking Changes or notable New Features, ask the user whether highlights are wanted.
3. Emit the category sections in the order from release-notes-template.md (🚀 New Features, 🧪 Experimental, 🔥 Breaking Changes, ⚠️ Deprecations, 🐛 Bug Fixes, 🧰 Maintenance), omitting any empty section. Each line is - <PR title> (#<n>). Combine PRs that deliver the same feature/change onto one line with all their numbers in a single bracket group in ascending order, e.g. - <title> (#3434 #3456 #3467) (common for paired sync/async PRs or a feature split across follow-ups) — see the grouping rule in references/release-notes-template.md.
4. End with the contributors footer: the thank-you line and the de-duplicated, space-separated list of @<author> handles for every included PR.

5. Save the draft as a local Markdown file

Write the assembled notes to a local Markdown file so the maintainer can review it and copy the contents into the GitHub release UI by hand. This file is a local review artifact only:

• Default path: release_notes/release_notes_<version>.md at the repo root (e.g. release_notes/release_notes_8.0.2.md). Create the release_notes/ folder if it does not exist. Confirm or accept an override path from the user.
• Do not commit, tag, push, or create/edit a GitHub release. The skill only writes the file in the working tree; the maintainer reviews it and publishes manually. (If the release_notes/ folder is not already git-ignored, mention that so it is not accidentally committed.)
• The file content is exactly what should be pasted into the release body — no extra wrapper or commentary inside the file.

After writing, report the file path and a short summary: the version, the previous tag, the per-section commit counts, the count of PRs whose category was inferred (and which ones), and any TODO markers left in the draft.

Verification

• Cross-check the commit count: the number of distinct PR numbers referenced across all change lines (a grouped line contributes all of its numbers), plus any skip-changelog/excluded PRs, should equal the commits in git log <prev-tag>..<branch> (minus merge commits). Grouping related PRs reduces the number of lines but not the number of PR references, so reconcile on PR numbers, not lines.
• Confirm section order and titles match references/release-notes-template.md and no empty section was emitted.
• Confirm every included PR number resolves to a real PR and every contributor handle is included once.
• Spot-check against the previous published release's formatting (run gh release view <prev-tag>).