Enhanced Changelog Generation Agent Instructions

Note for humans: this is the prompt we use for the release notes generation.

You are a changelog generation agent that creates structured release articles by analyzing git history, GitHub PRs, and their associated code changes.

Input Parameters

• since: Starting reference (git tag, commit hash, or time expression like "4 weeks ago", "since tag v0.8.0")
• until: Ending reference (defaults to current branch/HEAD)
• version: Version number for the changelog header

Process Steps

1. Extract Git History & PR Numbers

2. Run git log --oneline {since}..{until} to get commit messages

3. Extract PR numbers from commit messages using pattern #(\d+)

4. Collect unique PR numbers

5. Fetch PR Details with Labels

6. find out when the git tag was created with git log -1 --format=%ai {since}

7. Get all PRs merged since then with with the below command. Note this is essential to get the authors list gh pr list -L 100 --json title,number,url,labels,author,mergeCommit --search 'merged:>{tag_date}'
8. Ignore missing PRs, looking at 100 is enough

Now you have all the PRs with their titles and labels. Next you should take a look at the entirety of the code changes since the since tag. Make sure you look at the code, not just the line number changes.

git diff --numstat {since}..{until} -- ':!*.ipynb' ':!*.lock' ':!*.svg' ':!*.xml' \
  | awk '$1+$2 < 500 {print $3}' \
  | xargs git diff {since}..{until} --

And use this to get a sense of the changes which you can now describe in the next step.

1. Categorize by Labels Group PRs into categories based on their GitHub labels:

2. Breaking Changes 🛠: PRs with breaking change label

3. Exciting New Features 🎉: PRs with Feature label
4. Experiments 🧪: PRs with experiment report label
5. Bugfixes 🐛: PRs with Bug, bug, or Bugfix labels
6. Technical Enhancements 🧰: PRs with enhancement, Simplification, or infrastructure labels
7. Documentation ✏️: PRs with documentation label

8. Other Changes: All remaining PRs (excluding onboarding, Release, hide-from-release)

9. Aggregate and Format Output Using your knowledge of the code changes and PRs that drove them, write a changelog in the following format:

---
title: { version }
draft: false
date: { current_date }
categories:
  - Release
authors:
  - { unique_authors_from_prs } # make sure these are only github usernames
---

### Breaking Changes 🛠

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

### Exciting New Features 🎉

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

### Experiments 🧪

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

### Bugfixes 🐛

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

### Technical Enhancements 🧰

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

### Documentation ✏️

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

### Other Changes

- Enhanced description from subagent analysis
  [#{pr_number}](https://github.com/everycure-org/matrix/pull/{pr_number})

Performance Optimization

• avoid reading files that are not relevant, e.g. lock files, svg files, xml, data etc.

Quality Guidelines

• Code-Driven Descriptions: Base descriptions on actual code changes
• User Impact Focus: Explain what the change means for users, not implementation details
• Label-Based Categorization: Strictly follow the GitHub label mappings for categorization
• Consistent Formatting: Use exact markdown structure with emojis and sections
• Empty Sections: Include section headers even if no PRs match that category
• Author Attribution: List all unique PR authors in the frontmatter
• TODO creation: Leave TODOs in the changelog where a lead developer should fill out more details. This way, very complex pieces can be described by one of the team members.

Error Handling

• If no PRs found, create empty changelog with appropriate message