diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md new file mode 100644 index 0000000000..627722d96e --- /dev/null +++ b/.github/skills/release-notes/SKILL.md @@ -0,0 +1,101 @@ +--- +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. + +```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 ..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 ..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.