release-notes

name	release-notes
description	Generate release notes for the dotnet/diagnostics repository. Use when asked to generate release notes, a release summary, or a changelog.

Release Notes Generation

Process

1. Determine the baseline

Find the last published GitHub release — not the latest git tag. This repo may have many version tags (e.g., v10.0.*, v11.0.*) that don't correspond to published releases.

# Get the most recent published GitHub release tag for dotnet/diagnostics
release_tag=$(gh release list --repo dotnet/diagnostics --limit 1 --json tagName --jq '.[0].tagName')
echo "$release_tag"

The last published release may be on a different branch (e.g., release/9.0). Even so, use the tag directly in git log — do NOT use git merge-base. The release branch often contains snap/backport merges that bring main commits into the release, so merge-base returns an ancestor that is already included in the release tag. Instead:

# Correct: use the tag directly — git handles cross-branch reachability
git log <release-tag>..HEAD --oneline --first-parent

This ensures commits already reachable from the release tag (via snap merges or backports) are excluded.

2. Get the commit list

List all first-parent commits from the release tag to HEAD, excluding dependency flow PRs:

git log <release-tag>..HEAD --oneline --first-parent

Filter out:

• [main] Update dependencies from *
• Update dependencies from *
• Pure test infrastructure changes (test reorganization, CI image updates, SDK bumps)
• Build/CI plumbing (SDK updates, pipeline config, dependabot changes)

3. Investigate each PR

For each user-facing PR, launch parallel explore agents (one per group of 3-5 related PRs) to read:

• PR body (get method)
• Review comments (get_review_comments method)
• General comments (get_comments method)

Focus on:

• What user-visible behavior changed
• Why — what issue it solves, what feature it adds
• Breaking changes or UX surprises discussed in review threads
• Concrete examples (before/after output, error messages)

4. Write the release notes

Follow the format used in the latest release to get a sense of the current format used. For example, for v9.0.661903 the structure follows the following pattern:

### General announcements

Brief summary.

### dotnet-dump / SOS

- **Feature/fix name**: Description focusing on WHY and user impact. (#PR)

#### SOS Bug Fixes

- **Command affected**: What was wrong, what's fixed. (#PR)

### dotnet-trace

- **collect-linux improvements**: Group related sub-items.

### dotnet-counters

- **Feature**: Description. (#PR)

### Microsoft.Diagnostics.NETCore.Client

- **Feature**: Description. (#PR)

### Other notable changes

- Items that don't fit above categories.

5. Style guidelines

• Focus on why a change matters to users, not implementation details
• Include issue references where available: ([#1234](https://github.com/dotnet/diagnostics/issues/1234), #5678)
• Group related fixes (e.g., all collect-linux terminal fixes together)
• Call out breaking changes or UX changes explicitly
• Omit purely internal changes (refactors, test moves, CI config) unless they have user impact
• Use bold for command names and flags: !dumpheap -stat -bycount

Example output

See the release at https://github.com/dotnet/diagnostics/releases/tag/v9.0.661903 for format reference.