| name | release-notes |
| description | Generate release notes between two git tags with categorized PR summaries and author attribution |
| argument-hint | <git-tag> [-- <previous-tag>] |
Generate Release Notes
Parse $ARGUMENTS to extract:
- Everything before
-- is the release tag (e.g. 1.22.0). Referred to as TAG below.
- Everything after
-- is an optional previous tag override. If absent, auto-detect the previous tag.
Step 1: Validate the tag
Check that TAG exists as a git tag:
git tag -l TAG
If the tag does not exist, stop with an error: "Tag TAG not found. Please create the tag first and re-run."
Step 2: Determine the previous tag
If a previous tag was provided in $ARGUMENTS, validate it exists and use it as LOWER.
Otherwise, find the previous tag automatically:
git tag --sort=-v:refname
Walk the sorted list to find the tag immediately before TAG (by version order). Set that as LOWER.
Validate LOWER exists. Stop with an error if no previous tag can be determined.
Step 3: Gather commits
Get all commits between the two tags:
git log --oneline LOWER..TAG
Filter out:
- Merge commits (starting with "Merge pull request" or "Merge branch")
- Version bump commits (starting with "bumps to version" or "bumps to")
Extract PR numbers from the remaining commit messages (pattern #NNNN). Every PR number must appear in the final release notes — none may be silently dropped.
Step 4: Fetch PR metadata
For each PR number, fetch metadata using gh. Use Task agents to run in parallel batches for efficiency:
gh pr view NUMBER --repo dlt-hub/dlt --json number,title,labels,body,author
Collect for each PR:
- number: PR number
- title: PR title
- author:
author.login
- labels: list of label names
- body: PR description (first 500 chars sufficient for categorization)
Handling low-quality PR titles or descriptions
If a PR title is vague (e.g. just an issue number, single word) or the body is empty/unhelpful:
- Check if the PR references an issue (e.g.
fixes #NNN, closes #NNN, #NNN in body). If so, fetch the issue:
gh issue view NNN --repo dlt-hub/dlt --json title,body
- If still unclear, look at the PR diff to understand what changed:
gh pr diff NUMBER --repo dlt-hub/dlt
- Write a clear, accurate summary based on what you find.
Step 5: Categorize PRs
Assign each PR to exactly one category using these rules (evaluated in order). Every PR must be classified — verify the total count matches.
Breaking Changes
Collect separately (appears at the top, not a standalone category — the PR also appears in its main category). A PR has breaking changes if:
- It has a
breaking label, OR
- Its body contains "breaking change" (case-insensitive), OR
- Its title contains "breaking"
Extract the specific breaking change description from the PR body.
Highlights
A PR is a highlight if:
- It has a
highlight label, OR
- It is a significant new feature (title starts with
feat or (feat)) AND the change is impactful — meaning it introduces a new user-facing capability, enables a major use case, or represents substantial effort
- Use judgment: not every feature is a highlight. A highlight should be something users would be excited about.
Highlighted PRs also appear in their main category (Core Library, etc.) but with a brief entry pointing to the Highlights section.
Docs
- Title or body indicates documentation-only changes
- Files changed are only in
docs/
- Has
documentation label
Chores
- CI/CD improvements, test infrastructure, repo maintenance
- Has labels like
ci full, tech-debt, ci
- Title starts with
chore, repo:, ci:, or the change only affects tests/tooling
Core Library
Everything else — features, bug fixes, enhancements to the library itself.
Step 6: Identify new contributors
For each release author, find their first ever merged PR:
gh search prs --repo dlt-hub/dlt --author AUTHOR --merged --sort created --order asc --limit 1 --json number,createdAt
A contributor is new if their first merged PR number falls within the LOWER..TAG commit range.
Step 7: Format the release notes
Write the notes in this exact structure:
## dlt TAG Release Notes
## Breaking Changes
(Only if there are breaking changes. Numbered list.)
1. **Short description** (#NUMBER @author) — Explanation of what broke and how it affects users.
## Highlights
- **Feature name** (#NUMBER @author) — Description of the feature and why it matters.
## Core Library
- **Feature/fix name** (#NUMBER @author) — Brief description.
- **Fix: short description** (#NUMBER @author)
## Docs
- Description (#NUMBER @author)
## Chores
- **Title** (#NUMBER @author) — Brief description if non-obvious.
## New Contributors
- @author made their first contribution in #NUMBER
Formatting rules:
- PR references use
#NUMBER format (GitHub auto-links them)
- Authors use
@login format (GitHub auto-links them)
- Features and significant fixes get bold titles with em-dash descriptions
- Minor fixes can be single-line bold entries without descriptions
- Omit empty sections entirely (including New Contributors if none)
- Within Core Library, group features first, then fixes
Step 8: Present for approval
Display the formatted release notes to the user for review. Include a summary:
- Total PRs analyzed
- Breakdown by category (with counts)
- Number of unique contributors (and how many are new)
- List any PRs where you had to infer the description from issue or diff
Ask the user to approve or request changes before writing.
Step 9: Write to file
Only after user approval, write the release notes to /tmp/release-notes-TAG.md.
Report the file path to the user.
