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:

1. 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
   

2. If still unclear, look at the PR diff to understand what changed:

   gh pr diff NUMBER --repo dlt-hub/dlt
   

3. 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.