From ca06193e7532c71eaa76ecc156a2ff96042fd669 Mon Sep 17 00:00:00 2001 From: Juan Sebastian Hoyos Ayala <19413848+hoyosjs@users.noreply.github.com> Date: Tue, 21 Apr 2026 00:36:00 -0700 Subject: [PATCH 1/3] Add simple release note creation skill --- .github/skills/release-notes/SKILL.md | 100 ++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 .github/skills/release-notes/SKILL.md diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md new file mode 100644 index 0000000000..358d57aafc --- /dev/null +++ b/.github/skills/release-notes/SKILL.md @@ -0,0 +1,100 @@ +--- +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 +# Query the GitHub releases API for the last published release +# Use the github-mcp-server or the GitHub API directly +``` + +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 previous releases (see `v9.0.661903` for reference). Structure: + +```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. From beddeaf38dfa5eb2f5696faadb0633dd03e77a38 Mon Sep 17 00:00:00 2001 From: Juan Hoyos <19413848+hoyosjs@users.noreply.github.com> Date: Fri, 24 Apr 2026 16:33:01 -0700 Subject: [PATCH 2/3] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/skills/release-notes/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md index 358d57aafc..42923a0232 100644 --- a/.github/skills/release-notes/SKILL.md +++ b/.github/skills/release-notes/SKILL.md @@ -12,8 +12,9 @@ description: Generate release notes for the dotnet/diagnostics repository. Use w 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 -# Query the GitHub releases API for the last published release -# Use the github-mcp-server or the GitHub API directly +# 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: From 7e8c1a41272a51e4884a52e6ff1b6c59c0bea76e Mon Sep 17 00:00:00 2001 From: Juan Hoyos <19413848+hoyosjs@users.noreply.github.com> Date: Fri, 24 Apr 2026 16:35:01 -0700 Subject: [PATCH 3/3] Apply suggestion from @hoyosjs --- .github/skills/release-notes/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md index 42923a0232..627722d96e 100644 --- a/.github/skills/release-notes/SKILL.md +++ b/.github/skills/release-notes/SKILL.md @@ -55,7 +55,7 @@ Focus on: ### 4. Write the release notes -Follow the format used in previous releases (see `v9.0.661903` for reference). Structure: +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