release-notes

# 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: ```markdown ## 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.