release-notes

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