diff --git a/.github/agents/whats-new-from-release-notes.agent.md b/.github/agents/whats-new-from-release-notes.agent.md new file mode 100644 index 000000000000..d045800ad517 --- /dev/null +++ b/.github/agents/whats-new-from-release-notes.agent.md @@ -0,0 +1,229 @@ +--- +name: whats-new-release-notes +description: > + Creates or updates the "What's New in ASP.NET Core" release notes article + by generating include files from dotnet/core preview release notes and + adding them to the What's New article in dotnet/AspNetCore.Docs. + Use this agent when processing new .NET preview release notes into the + What's New article, or when checking for incremental updates to + already-processed release notes. +tools: + - githubread + - lexical-code-search + - semantic-code-search +ai-usage: ai-assisted +author: tdykstra +ms.author: wpickett +ms.date: 03/11/2026 +--- + +# What's New Release Notes Agent for ASP.NET Core Documentation + +## Goal + +Transform ASP.NET Core preview release notes from the `dotnet/core` repository +into include files for the cumulative "What's New in ASP.NET Core in .NET {VERSION}" +article in `dotnet/AspNetCore.Docs`. This agent handles both initial creation of +include files for a new preview and incremental updates when release notes are +revised after initial processing. + +## Inputs + +When invoking this agent, provide the following context (or let the agent auto-discover): + +| Parameter | Required | Default | Description | +|-----------|----------|---------|-------------| +| `VERSION` | Yes | — | The .NET major version (e.g., `11.0`) | +| `PREVIEW` | No | *(auto-discover)* | The specific preview to process (for example, `preview3`). If omitted, the agent discovers the latest unprocessed preview. | +| `SOURCE_REF` | No | `main` | The branch or commit in `dotnet/core` to read release notes from. Use this when release notes exist on a branch before merging to main. | +| `MODE` | No | `auto` | One of: `auto`, `new-preview`, `incremental`. Controls whether the agent creates files for a new preview, updates existing ones, or auto-detects. | + +## Skill Dependencies + +* **Skill**: [whats-new-include-content-rules](../skills/whats-new-include-content-rules/SKILL.md) — content rules and formatting standards for include files. + +--- + +## Step 0: Gather context and detect what's already done + +### 0a: Resolve source parameters + +Before reading any files, resolve the following parameters. If the invoker +provided explicit values, use them. Otherwise, auto-discover. + +| Parameter | Required | Default | Description | +|-----------|----------|---------|-------------| +| `VERSION` | Yes | — | The .NET major version (e.g., `11.0`) | +| `PREVIEW` | No | *(auto-discover)* | The specific preview to process (e.g., `preview3`). If omitted, the agent discovers the latest unprocessed preview. | +| `SOURCE_REF` | No | `main` | The branch or commit in `dotnet/core` to read release notes from. Use this when release notes exist on a branch before merging to main. | +| `MODE` | No | `auto` | One of: `auto`, `new-preview`, `incremental`. Controls whether the agent creates files for a new preview, updates existing ones, or auto-detects. | + +1. **Determine `SOURCE_REF`**: If not provided, default to `main`. + +2. **Discover available previews** in `dotnet/core` at `SOURCE_REF`: + List the directories under `release-notes/{VERSION}/preview/` and identify + all `preview{N}` folders that contain an `aspnetcore.md` file. + +3. **Determine which preview to process**: + - If `PREVIEW` was explicitly provided, use it. + - If `PREVIEW` was NOT provided, auto-discover: + a. List existing include files in `dotnet/AspNetCore.Docs` under + `aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}/includes/`. + b. Extract the set of preview suffixes already represented + (e.g., files ending in `-preview1.md` and `-preview2.md` + → previews 1 and 2 are covered). + c. Compare against available previews in `dotnet/core`. + d. If there is a preview in `dotnet/core` with NO corresponding + include files → that is the **new preview** to process. + e. If ALL previews have corresponding include files → enter + **incremental update mode** for the latest preview. + +4. **Determine `MODE`**: + - If `MODE` was explicitly set, use it. + - If `MODE` is `auto`: + - If the resolved preview has ZERO existing include files → `new-preview` + - If the resolved preview has existing include files → `incremental` + +5. **Report the resolved parameters** before proceeding: + ``` + Resolved parameters: + - VERSION: {VERSION} + - PREVIEW: {resolved preview} + - SOURCE_REF: {branch/ref} + - MODE: {new-preview | incremental} + - Source path: release-notes/{VERSION}/preview/{PREVIEW}/aspnetcore.md + ``` + +### 0b: Read the source release notes + +Read the source release notes from `dotnet/core` at ref `{SOURCE_REF}`: +`release-notes/{VERSION}/preview/{PREVIEW}/aspnetcore.md` + +Use `githubread` with the specific ref/branch to ensure you are reading +the correct version of the file. + +### 0c: Read the current What's New article + +Read the current What's New article in `dotnet/AspNetCore.Docs`: +`aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}.md` + +### 0d: List existing What's Newinclude files + +List all existing include files in: +`aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}/includes/` + +### 0e: Compare source vs. existing content + +* Identify features/sections in the source release notes that do NOT yet + have a corresponding include file. +* Identify existing include files whose content has materially changed in + the source release notes (beyond trivial formatting). +* Report your findings before making any changes. List: + - NEW features that need include files created + - EXISTING features that may need content updates + - Features already fully covered (no action needed) + +### 0f: Only create or update files for the delta + +Never recreate include files that already exist and are current. + +--- + +## Step 1: Create include files + +Load and follow all rules from the +[whats-new-include-content-rules](../skills/whats-new-include-content-rules/SKILL.md) +skill. That skill defines file naming, location, exclusions, content formatting, +xref usage, link rules, phrasing style, and the validation checklist. + +Apply those rules to create one include file per feature from the source +release notes. + +--- + +## Step 2: Update the What's New article + +File: `aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}.md` + +### Add include directives + +For each new include file, add a `[!INCLUDE]` directive in the appropriate +product area section: + +``` +[!INCLUDE[](~/release-notes/aspnetcore-{MAJOR_VERSION}/includes/{filename}.md)] +``` + +### Placement rules + +* Place new includes **after** any existing includes within each section. +* Maintain a blank line before and after each `[!INCLUDE]` directive. +* If a section heading exists but has no includes yet, add the include after + the section's introductory sentence. + +### Section mapping + +Map features from the release notes to the correct section in the What's New article: + +| Release notes area | What's New section | +|---|---| +| OpenAPI | `## OpenAPI` | +| Authentication, Identity, Passkeys | `## Authentication and authorization` | +| SignalR | `## SignalR` | +| Minimal APIs | `## Minimal APIs` | +| Kestrel, Servers | `## Miscellaneous` (or a dedicated section if one exists) | +| Performance | `## Miscellaneous` | +| Observability, OpenTelemetry | `## Miscellaneous` | +| Blazor | **SKIP — handled separately** | + +If a section doesn't exist in the What's New article but should, create it +following the established pattern: + +```markdown +## Section Name + +This section describes new features for Section Name. + +[!INCLUDE[](~/release-notes/aspnetcore-{MAJOR_VERSION}/includes/{filename}.md)] +``` + +### Update front matter on the What's New article + +* Set `ms.date` to today's date in `MM/DD/YYYY` format. +* Add `ai-usage: ai-assisted` if not already present. +* Do NOT change the existing `ms.date` format — it must be MM/DD/YYYY. + **Wrong**: `ms.date: 12/04/2025` when article was written on `03/10/2026`. + +### Breaking changes section + +* Do NOT comment out or remove the Breaking changes section. +* Ensure the link uses a relative path: + ```markdown + Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET. + ``` + +--- + +## Step 3: Validate + +Run the validation checklist from the +[whats-new-include-content-rules](../skills/whats-new-include-content-rules/SKILL.md) +skill. Additionally verify: + +- [ ] The What's New article `ms.date` is set to today's date +- [ ] All `[!INCLUDE]` directives are correctly placed with blank lines around them +- [ ] Section mapping matches the table above + +--- + +## Incremental update mode + +When invoked to check for updates (not a full new preview): + +1. Compare the current source release notes against the existing include files. +2. Report any new content, removed content, or modified content. +3. Only propose changes for genuine differences — not formatting-only changes. +4. If new features were added to the release notes after initial processing, + create new include files following all the rules above. +5. If existing feature descriptions were updated, propose edits to the + corresponding include files and note what changed. \ No newline at end of file diff --git a/.github/skills/whats-new-include-content-rules/SKILL.md b/.github/skills/whats-new-include-content-rules/SKILL.md new file mode 100644 index 000000000000..10a13c4f936a --- /dev/null +++ b/.github/skills/whats-new-include-content-rules/SKILL.md @@ -0,0 +1,175 @@ +--- +name: whats-new-include-content-rules +description: > + Content rules and formatting standards for ASP.NET Core What's New include files. + Use when creating or editing include files in aspnetcore/release-notes/*/includes/. + Covers heading levels, xref API references, link formatting, phrasing style, + breaking change designations, contributor acknowledgments, file naming, and exclusions. + Use for: What's New include file, release notes include, xref format, include content rules, + H3 heading level, relative link Microsoft Learn, include file naming convention. +--- + +# What's New Include File — Content Rules + +These rules encode corrections from past PR reviews. Follow them strictly when +creating or editing include files under `aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}/includes/`. + +## File creation rules + +### File location + +All include files go in: +`aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}/includes/` + +### File naming convention + +* Lowercase, hyphenated, descriptive names. +* Append the preview suffix to each filename: `-preview{N}` (e.g., `-preview2`). + **CRITICAL**: Every new file MUST include the preview suffix. This was a mistake + in the initial automation — a file was created without the suffix and had to be + corrected. +* Examples: + - `native-otel-tracing-preview2.md` + - `openapi-3-2-support-preview2.md` + - `infer-passkey-display-name-preview2.md` + - `performance-improvements-preview2.md` + +### One file per feature + +* Create one include file per feature or section. +* **Exception — Performance**: Combine all performance improvements into a + single `performance-improvements-preview{N}.md` file. + +### Exclusions — do NOT create include files for + +* **Do not create include files for Blazor features**: + * Blazor-related content is handled separately by the Blazor documentation team with separate PRs that merge into the What's New. + * Do **NOT** create any new include files for Blazor content. + * Do indicate in the PR description report which Blazor features are present in the release notes but not represented in the What's New article or includes. + +* **Do not create include files for the Bug fixes section**: Only document new features and improvements. +* **Community contributors list**: + * Do not create a standalone include file for the contributors list. + * DO preserve inline contributor thank-yous within feature sections (see below). + +--- + +## Content rules + +### Heading level + +* Use `###` (H3) headings — never `#` or `##`. Include files are embedded inside + a parent article that already uses `##` for section headings. + +### Remove preview-specific references + +* Do NOT mention the specific preview number in content (e.g., "In Preview 2…"). + The What's New article is cumulative for the entire .NET release. + +### Use `` for API references — not inline code + +* **Wrong**: `` `AddOpenApi()` `` +* **Correct**: `` +* **Wrong**: `` `BadHttpRequestException` `` +* **Correct**: `` +* When referencing an API type or method, always use `` + format. The xref ID must be verified from official dotnet-api-docs, not guessed. +* When referring to a dictionary/API concept (not a file), do NOT include file + extensions. For example, write `PasskeyAuthenticators` dictionary, not + `PasskeyAuthenticators.cs` dictionary. + +### Links — use relative paths for Microsoft Learn + +* **Wrong**: `[Breaking changes in .NET]([/dotnet/core/compatibility/breaking-changes](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes))` +* **Correct**: `[Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes)` +* Never nest a relative path inside an absolute URL as the href target. +* For Microsoft Learn cross-references, use relative URLs starting with `/`. + Do not include `https://learn.microsoft.com` or the `/en-us/` locale. + +### Links — external sites + +* For GitHub repository links, use full absolute URLs. +* For external non-Microsoft sites, use absolute URLs and strip locale segments. + +### Phrasing and style (lessons from reviewer feedback) + +* Use **"For more information, see [link text](url)."** — not em-dash + "see … for details." +* Use **present tense**, not future tense. + - **Wrong**: "Subsequent updates **will take** advantage of…" + - **Correct**: "Subsequent updates **take** advantage of…" +* Use **imperative voice** for instructions to readers. + - **Wrong**: "Developers can extend the mappings by…" + - **Correct**: "Extend the mappings by…" +* Move long lists of attributes/parameters to the **end** of the sentence for readability. + - **Wrong**: "…populates semantic convention attributes like `a`, `b`, `c`, and `d` on the request activity." + - **Correct**: "…populates semantic convention attributes on the request activity, such as `a`, `b`, `c`, and `d`." + +### Preserve special designations + +* If a section is marked as a **Breaking Change**, preserve that designation + in the include file heading: `### Feature name (Breaking Change)` +* If a section thanks a **community contributor** inline, preserve the + acknowledgment: `Thank you [@username](https://github.com/username) for this contribution!` + +### HTML comments + +* Properly close HTML comments with `-->`. Never leave an unclosed HTML comment. + +### Include files have NO front matter + +* Include files (in the `includes/` directory) do NOT get YAML front matter + (no `---` block with title, ms.date, etc.). They are raw Markdown fragments. + +--- + +## Validation checklist + +Before completing, verify: + +- [ ] Every new include filename ends with `-preview{N}`. +- [ ] No Blazor content was included. +- [ ] No bug-fix-only content was included. +- [ ] All `` IDs are verified (or explicitly flagged as needing verification). +- [ ] All links to Microsoft Learn use relative paths (no absolute URLs). +- [ ] All HTML comments are properly closed with `-->`. +- [ ] Include files have NO YAML front matter. +- [ ] Present tense is used throughout (not future tense). +- [ ] "For more information, see" pattern is used (not em-dash style). +- [ ] Community contributor acknowledgments are preserved. +- [ ] Breaking Change designations are preserved in headings. +- [ ] No preview-specific language, such as a preview number, appears in include file content. + +--- + +## Example: Correctly formatted include file + +```markdown +### OpenAPI 3.2.0 support (Breaking Change) + +`Microsoft.AspNetCore.OpenApi` now supports OpenAPI 3.2.0 through an updated dependency on `Microsoft.OpenApi` 3.3.1. This update includes breaking changes from the underlying library. For more information, see the [Microsoft.OpenApi upgrade guide](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-3.md). + +To generate an OpenAPI 3.2.0 document, specify the version when calling : + +```csharp +builder.Services.AddOpenApi(options => +{ + options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_2; +}); +⁣``` + +Subsequent updates take advantage of new capabilities in the 3.2.0 specification, such as item schema support for streaming events. + +Thank you [@baywet](https://github.com/baywet) for this contribution! +``` + +### What this example demonstrates + +* `###` heading (H3), not `##` +* Breaking Change designation preserved in heading +* "For more information, see" phrasing (not em-dash style) +* `` used for API method reference +* Present tense ("take advantage" not "will take advantage") +* Community contributor thank-you preserved +* No preview number mentioned in the body text +* No YAML front matter +* Relative link would be used for any Microsoft Learn references