dotnet · mdaigle · Mar 5, 2026 · Feb 27, 2026 · Feb 27, 2026 · Feb 27, 2026
@@ -1,29 +1,122 @@
 ---
 name: release-notes
-description: Generate release notes for a specific milestone of the Microsoft.Data.SqlClient project.
+description: Generate release notes for a specific milestone, covering all packages in the repository that have changes.
 argument-hint: <milestone>
 agent: agent
-tools: ['github/search_issues', 'edit/createFile', 'edit/editFiles', 'read/readFile']
+tools: ['edit/createFile', 'edit/editFiles', 'read/readFile']
 ---
 
 Generate release notes for the milestone "${input:milestone}".
 
-Steps:
-1. Fetch Milestone Items
-    - Search for all **merged** Pull Requests associated with the milestone "${input:milestone}" in the `dotnet/SqlClient` repository.
-    - Use `github/search_issues` with query `is:pr is:merged milestone:"${input:milestone}" repo:dotnet/SqlClient`.
-2. Analyze and Categorize
-    - Review the title and body of each PR. For PRs that are porting other PRs to current branch use `github/search_issues` with query `is:pr is:merged repo:dotnet/SqlClient <original PR number>` to get more context.
-    - Categorize them into: `Added`, `Fixed`, `Changed`, `Removed`.
-    - Ignore PRs that are labelled as `Area\Engineering`
-    - Identify the contributors for the "Contributors" section.
-3. Create Release Notes File
-    - Determine the correct path: `release-notes/<Major.Minor>/<Version>.md`.
-    - Create the file with the template contents from `release-notes/template/release-notes-template.md`.
-    - Fill in the template, following the instructions present in each section.
-4. Update CHANGELOG.md
-    - Add a new entry at the top of the list (under the Note).
-    - Include all the text from the Added, Fixed, Changed, Removed, etc. sections from the release notes.
-5. Update Release Directory README
-    - Update `release-notes/<Major.Minor>/README.md`.
-    - Add the new release to the table: `| <Date> | <Version> | [Release Notes](<Version>.md) |`.
+This repository ships multiple packages. Only generate release notes for packages that have relevant PRs in the milestone. All packages use the same template: [release-notes/template/release-notes-template.md](release-notes/template/release-notes-template.md).
+
+## Package Registry
+
+| Package | Release Notes Directory | How to Identify PRs |
+|---------|------------------------|---------------------|
+| `Microsoft.Data.SqlClient` | `release-notes/<Major.Minor>/` | Default — PRs not assigned to another package |
+| `Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider` | `release-notes/add-ons/AzureKeyVaultProvider/<Major.Minor>/` | Labels containing `AKV`, or PR titles/bodies/files referencing `AzureKeyVaultProvider`, `add-ons/`, or `AlwaysEncrypted.AzureKeyVaultProvider` |
+| `Microsoft.SqlServer.Server` | `release-notes/MSqlServerServer/<Major.Minor>/` | PR titles/bodies/files referencing `Microsoft.SqlServer.Server` or `src/Microsoft.SqlServer.Server/` |
+| `Microsoft.Data.SqlClient.Extensions.Abstractions` | `release-notes/Extensions/Abstractions/<Major.Minor>/` | PR titles/bodies/files referencing `Extensions.Abstractions` |
+| `Microsoft.Data.SqlClient.Extensions.Azure` | `release-notes/Extensions/Azure/<Major.Minor>/` | PR titles/bodies/files referencing `Extensions.Azure` |
+| `Microsoft.Data.SqlClient.Extensions.Logging` | `release-notes/Extensions/Logging/<Major.Minor>/` | PR titles/bodies/files referencing `Extensions.Logging` |
+
+## Version and Dependency Lookup
+
+Each package has its own versioning and dependency sources. Use these to determine package versions and dependency lists:
+
+| Package | Version Source | Dependency Source |
+|---------|---------------|-------------------|
+| `Microsoft.Data.SqlClient` | [tools/props/Versions.props](tools/props/Versions.props) (`MdsVersionDefault`) | [Directory.Packages.props](Directory.Packages.props) and the [project file](src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj) |
+| `AzureKeyVaultProvider` | [tools/props/Versions.props](tools/props/Versions.props) (`AkvVersionDefault`) | [AKV project file](src/Microsoft.Data.SqlClient/add-ons/AzureKeyVaultProvider/Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider.csproj) and [Directory.Packages.props](Directory.Packages.props) |
+| `Microsoft.SqlServer.Server` | [tools/props/Versions.props](tools/props/Versions.props) (`SqlServerPackageVersion`) | [SqlServer project file](src/Microsoft.SqlServer.Server/Microsoft.SqlServer.Server.csproj) |
+| `Extensions.Abstractions` | [AbstractionsVersions.props](src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/AbstractionsVersions.props) | [Abstractions.csproj](src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/Abstractions.csproj) |
+| `Extensions.Azure` | [AzureVersions.props](src/Microsoft.Data.SqlClient.Extensions/Azure/src/AzureVersions.props) | [Azure.csproj](src/Microsoft.Data.SqlClient.Extensions/Azure/src/Azure.csproj) |
+| `Extensions.Logging` | [LoggingVersions.props](src/Microsoft.Data.SqlClient.Extensions/Logging/src/LoggingVersions.props) | [Logging.csproj](src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj) |
+
+Concrete dependency versions (e.g., `Azure.Core 1.49.0`) are centrally managed in [Directory.Packages.props](Directory.Packages.props). Framework-conditional versions (e.g., `net9.0` vs everything else) are handled by `Condition` attributes in the same file.
+
+## Skills
+
+This prompt uses the following skill:
+- [fetch-milestone-prs](.github/skills/fetch-milestone-prs/SKILL.md) — Fetches all merged PR metadata for the milestone
+
+## Steps
+
+### 1. Fetch Milestone Items
+
+- Follow the instructions in the [fetch-milestone-prs](.github/skills/fetch-milestone-prs/SKILL.md) skill to fetch all merged PRs for the milestone "${input:milestone}".
+- The output will be saved to `.milestone-prs/${input:milestone}/` with individual JSON files per PR and an `_index.json` summary.
+
+### 2. Analyze and Categorize
+
+- Read the `_index.json` file to get an overview of all PRs. Read individual PR JSON files for full details (title, body, labels).
+- For PRs that are porting other PRs to the current branch, read the original PR's JSON file or look up the original PR number mentioned in the body for more context.
+- Categorize PRs into: `Added`, `Fixed`, `Changed`, `Removed`.
+- Ignore PRs labelled `Area\Engineering` (use the `has_engineering_label` field in the JSON).
+- Identify the contributors for the "Contributors" section.
+- **Assign each PR to one or more packages** using the identification rules in the Package Registry table. A PR may be relevant to multiple packages. PRs not matching any non-core package belong to `Microsoft.Data.SqlClient`.
+
+### 3. Enrich Feature Sections with Issue Context
+
+For significant features or bug fixes that reference a GitHub issue:
+
+1. Read the referenced issue to understand the original request, use cases, and community context.
+2. Use this information to write richer *Who Benefits* and *Impact* sections — don't just restate the PR description.
+3. Include the issue link alongside PR links (e.g., `([#1108](https://github.com/dotnet/SqlClient/issues/1108), [#3680](https://github.com/dotnet/SqlClient/pull/3680))`).
+
+### 4. Verify API Names from Source Code
+
+When release notes reference a public API (property, method, class):
+
+1. Search the source code (`src/Microsoft.Data.SqlClient/src/`) to confirm the exact name, type, and signature.
+2. Check XML doc comments for usage warnings or caveats that should be included in the *Impact* section.
+3. Never guess API names from PR titles — always verify against the actual code.
+
+### 5. Generate Release Notes for Each Package
+
+For each package that has relevant PRs in the milestone:
+
+1. **Determine the package version** using the Version Source from the lookup table above. Read the actual props/project file to find the version.
+
+2. **Create the release notes file** at the path shown in the Package Registry table: `<Directory>/<Version>.md`.
+   - Use the template from [release-notes/template/release-notes-template.md](release-notes/template/release-notes-template.md).
+   - Fill in the template following the instructions in each section.
+   - Only include sections (Added, Changed, Fixed, Removed) that have entries.
+   - Look up dependencies using the Dependency Sources from the lookup table above. Resolve concrete versions from [Directory.Packages.props](Directory.Packages.props).
+   - List dependencies per target framework. Use the project file's `<TargetFrameworks>` to determine which frameworks to list.
+   - Omit the Contributors section for packages with no public contributors.
+
+3. **Create or update the version README** at `<Directory>/README.md`. Follow the existing format — see [release-notes/add-ons/AzureKeyVaultProvider/6.1/README.md](release-notes/add-ons/AzureKeyVaultProvider/6.1/README.md) for reference:
+
+   ```markdown
+   # <Full Package Name> <Major.Minor> Releases
+
+   The following `<Full Package Name>`
+   <Major.Minor> releases have been shipped:
+
+   | Release Date | Description | Notes |
+   | :-- | :-- | :--: |
+   | <Date> | <Version> | [Release Notes](<Version>.md) |
+   ```
+
+4. **Skip packages without changes.** If a package has no relevant PRs in the milestone, do not create release notes for it. Report which packages had changes and which did not.
+
+### 6. Update CHANGELOG.md
+
+- Add a new entry at the top of the list (under the Note) in [CHANGELOG.md](CHANGELOG.md).
+- Include all the text from the Added, Fixed, Changed, Removed, etc. sections from the core `Microsoft.Data.SqlClient` release notes.
+- If other packages also changed, include a brief summary line for each (e.g., "Released Microsoft.Data.SqlClient.Extensions.Azure 1.0.0-preview1. See [release notes](...)."). The detailed notes live in the per-package release notes files.
+
+### 7. Update Top-Level Release Notes README
+
+- Update [release-notes/README.md](release-notes/README.md):
+  - Add the new release to the appropriate package section.
+  - If a section for the package doesn't yet exist, add one following the existing pattern (see the `AzureKeyVaultProvider` and `Microsoft.SqlServer.Server` sections for reference).
+  - If the section already exists, add the new version link to its Release Information list.
+
+## Notes
+
+- Packages may ship as preview or stable independently. Use the actual version from the project/spec files.
+- The directory structure mirrors existing conventions: `add-ons/AzureKeyVaultProvider/` for AKV, `MSqlServerServer/` for SqlServer, and `Extensions/<PackageName>/` for the new extension packages.
+- When referencing code samples, link to files in the `doc/samples/` directory if a relevant sample exists.
@@ -0,0 +1,135 @@
+---
+name: fetch-milestone-prs
+description: Fetches all merged pull requests for a given GitHub milestone and saves their metadata as individual JSON files. Use this skill when asked to retrieve PRs for a milestone, gather PR data for release notes, or collect milestone PR metadata.
+---
+
+This skill retrieves all merged pull requests associated with a GitHub milestone and saves each PR's metadata as a separate JSON file for downstream processing (e.g., release notes generation, changelog creation).
+
+## When to Use This Skill
+
+- User asks to fetch or retrieve PRs for a milestone
+- User wants to gather PR data before generating release notes
+- User needs milestone PR metadata for analysis or categorization
+- User mentions a milestone name and wants to see what PRs were included
+- As a prerequisite step before invoking the `release-notes` prompt
+
+## Prerequisites
+
+- The `gh` CLI must be installed and authenticated (`gh auth login`)
+- Python 3.8+ must be available
+
+## Instructions
+
+1. **Identify the milestone name** from the user's request. This is typically a version string like `7.0.0-preview4`, `6.1.5`, etc.
+
+2. **Identify the repository** (optional). Defaults to `dotnet/SqlClient`. If the user specifies a different repo, pass it via `--repo`.
+
+3. **Run the fetch script** located in this skill's directory:
+
+   ```bash
+   python .github/skills/fetch-milestone-prs/fetch-milestone-prs.py <milestone> [--repo OWNER/REPO] [--output-dir DIR]
+   ```
+
+   Examples:
+   ```bash
+   # Default: outputs to .milestone-prs/<milestone>/
+   python .github/skills/fetch-milestone-prs/fetch-milestone-prs.py 7.0.0-preview4
+
+   # Custom output directory
+   python .github/skills/fetch-milestone-prs/fetch-milestone-prs.py 7.0.0-preview4 --output-dir ./my-prs
+
+   # Different repo
+   python .github/skills/fetch-milestone-prs/fetch-milestone-prs.py 7.0.0-preview4 --repo dotnet/efcore
+   ```
+
+4. **Verify the output** by checking the generated `_index.json` file in the output directory. It contains a summary of all fetched PRs.
+
+5. **Report results** to the user:
+   - Total merged PRs found
+   - Total skipped (closed but not merged)
+   - Output directory path
+   - Mention that each PR is in a separate `<number>.json` file and the index is at `_index.json`
+
+## Output Format
+
+### Directory structure
+```
+.milestone-prs/<milestone>/
+├── _index.json          # Summary index of all PRs
+├── 1234.json            # Individual PR metadata
+├── 1235.json
+└── ...
+```
+
+### Individual PR file (`<number>.json`)
+Each file contains:
+```json
+{
+  "number": 1234,
+  "title": "PR title",
+  "author": "github-username",
+  "author_association": "MEMBER",
+  "labels": ["label1", "label2"],
+  "assignees": ["user1"],
+  "state": "closed",
+  "merged": true,
+  "merged_at": "2026-01-15T12:00:00Z",
+  "merge_commit_sha": "abc123...",
+  "created_at": "2026-01-10T10:00:00Z",
+  "closed_at": "2026-01-15T12:00:00Z",
+  "html_url": "https://github.com/dotnet/SqlClient/pull/1234",
+  "body": "Full PR description markdown...",
+  "comments_count": 5,
+  "is_merged_pr": true,
+  "has_public_api_label": false,
+  "has_engineering_label": false,
+  "has_test_label": true
+}
+```
+
+### Index file (`_index.json`)
+```json
+{
+  "milestone": "7.0.0-preview4",
+  "repo": "dotnet/SqlClient",
+  "total_closed": 76,
+  "total_merged": 74,
+  "total_skipped": 2,
+  "prs": [
+    {
+      "number": 1234,
+      "title": "PR title",
+      "author": "github-username",
+      "labels": ["label1"],
+      "merged_at": "2026-01-15T12:00:00Z",
+      "has_public_api_label": false,
+      "has_engineering_label": false,
+      "has_test_label": true
+    }
+  ]
+}
+```
+
+## Derived Fields
+
+The script computes these boolean flags for easy categorization:
+
+| Field | Logic |
+|-------|-------|
+| `has_public_api_label` | Any label contains "Public API :new:" |
+| `has_engineering_label` | Any label contains "Engineering" |
+| `has_test_label` | Any label contains "Test" |
+
+## Error Handling
+
+- If the milestone is not found, the script prints available milestones and exits. Ask the user to verify the milestone name.
+- If `gh` is not authenticated, the script will fail with an auth error. Instruct the user to run `gh auth login`.
+- If a specific PR detail fetch fails, the script exits. This is rare but can happen with API rate limits — suggest waiting and retrying.
+- On Windows, if encoding errors occur, the script uses `errors="replace"` to handle non-UTF-8 characters gracefully.
+
+## Using Output with Other Workflows
+
+The output files are designed to be consumed by:
+- The `release-notes` prompt — tag the output directory (e.g., `@.milestone-prs/7.0.0-preview4/*`) when invoking it
+- Manual analysis — read `_index.json` for a quick overview, individual files for PR details
+- Any script or agent that needs structured PR metadata