Skip to content

Commit 98208c0

Browse files
wadepickettwadepickett
authored
Merge pull request #36900 from dotnet/main
Merge to Live
2 parents d8e068b + 94e8f38 commit 98208c0

2 files changed

Lines changed: 404 additions & 0 deletions

File tree

‎.github/agents/whats-new-from-release-notes.agent.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
name: whats-new-release-notes
3+
description: >
4+
Creates or updates the "What's New in ASP.NET Core" release notes article
5+
by generating include files from dotnet/core preview release notes and
6+
adding them to the What's New article in dotnet/AspNetCore.Docs.
7+
Use this agent when processing new .NET preview release notes into the
8+
What's New article, or when checking for incremental updates to
9+
already-processed release notes.
10+
tools:
11+
- githubread
12+
- lexical-code-search
13+
- semantic-code-search
14+
ai-usage: ai-assisted
15+
author: tdykstra
16+
ms.author: wpickett
17+
ms.date: 03/11/2026
18+
---
19+
20+
# What's New Release Notes Agent for ASP.NET Core Documentation
21+
22+
## Goal
23+
24+
Transform ASP.NET Core preview release notes from the `dotnet/core` repository
25+
into include files for the cumulative "What's New in ASP.NET Core in .NET {MAJOR_VERSION}"
26+
article in `dotnet/AspNetCore.Docs`. This agent handles both initial creation of
27+
include files for a new preview and incremental updates when release notes are
28+
revised after initial processing.
29+
30+
## Inputs
31+
32+
When invoking this agent, provide the following context (or let the agent auto-discover):
33+
34+
| Parameter | Required | Default | Description |
35+
|-----------|----------|---------|-------------|
36+
| `VERSION` | Yes | — | The .NET major version (e.g., `11.0`) |
37+
| `PREVIEW` | No | *(auto-discover)* | The specific preview to process (for example, `preview3`). If omitted, the agent discovers the latest unprocessed preview. |
38+
| `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. |
39+
| `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. |
40+
41+
## Skill Dependencies
42+
43+
* **Skill**: [whats-new-include-content-rules](../skills/whats-new-include-content-rules/SKILL.md) — content rules and formatting standards for include files.
44+
45+
---
46+
47+
## Step 0: Gather context and detect what's already done
48+
49+
### 0a: Resolve source parameters
50+
51+
Before reading any files, resolve the following parameters. If the invoker
52+
provided explicit values, use them. Otherwise, auto-discover.
53+
54+
1. **Determine `SOURCE_REF`**: If not provided, default to `main`.
55+
56+
2. **Discover available previews** in `dotnet/core` at `SOURCE_REF`:
57+
List the directories under `release-notes/{VERSION}/preview/` and identify
58+
all `preview{N}` folders that contain an `aspnetcore.md` file.
59+
60+
3. **Determine which preview to process**:
61+
- If `PREVIEW` was explicitly provided, use it.
62+
- If `PREVIEW` was NOT provided, auto-discover:
63+
a. List existing include files in `dotnet/AspNetCore.Docs` under
64+
`aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}/includes/`.
65+
b. Extract the set of preview suffixes already represented
66+
(e.g., files ending in `-preview1.md` and `-preview2.md`
67+
→ previews 1 and 2 are covered).
68+
c. Compare against available previews in `dotnet/core`.
69+
d. If there is a preview in `dotnet/core` with NO corresponding
70+
include files → that is the **new preview** to process.
71+
e. If ALL previews have corresponding include files → enter
72+
**incremental update mode** for the latest preview.
73+
74+
4. **Determine `MODE`**:
75+
- If `MODE` was explicitly set, use it.
76+
- If `MODE` is `auto`:
77+
- If the resolved preview has ZERO existing include files → `new-preview`
78+
- If the resolved preview has existing include files → `incremental`
79+
80+
5. **Report the resolved parameters** before proceeding:
81+
```
82+
Resolved parameters:
83+
- VERSION: {VERSION}
84+
- PREVIEW: {resolved preview}
85+
- SOURCE_REF: {branch/ref}
86+
- MODE: {new-preview | incremental}
87+
- Source path: release-notes/{VERSION}/preview/{PREVIEW}/aspnetcore.md
88+
```
89+
90+
### 0b: Read the source release notes
91+
92+
Read the source release notes from `dotnet/core` at ref `{SOURCE_REF}`:
93+
`release-notes/{VERSION}/preview/{PREVIEW}/aspnetcore.md`
94+
95+
Use `githubread` with the specific ref/branch to ensure you are reading
96+
the correct version of the file.
97+
98+
### 0c: Read the current What's New article
99+
100+
Read the current What's New article in `dotnet/AspNetCore.Docs`:
101+
`aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}.md`
102+
103+
### 0d: List existing What's New include files
104+
105+
List all existing include files in:
106+
`aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}/includes/`
107+
108+
### 0e: Compare source vs. existing content
109+
110+
* Identify features/sections in the source release notes that do NOT yet
111+
have a corresponding include file.
112+
* Identify existing include files whose content has materially changed in
113+
the source release notes (beyond trivial formatting).
114+
* Report your findings before making any changes. List:
115+
- NEW features that need include files created
116+
- EXISTING features that may need content updates
117+
- Features already fully covered (no action needed)
118+
119+
### 0f: Only create or update files for the delta
120+
121+
Never recreate include files that already exist and are current.
122+
123+
---
124+
125+
## Step 1: Create include files
126+
127+
Load and follow all rules from the
128+
[whats-new-include-content-rules](../skills/whats-new-include-content-rules/SKILL.md)
129+
skill. That skill defines file naming, location, exclusions, content formatting,
130+
xref usage, link rules, phrasing style, and the validation checklist.
131+
132+
Apply those rules to create one include file per feature from the source
133+
release notes.
134+
135+
---
136+
137+
## Step 2: Update the What's New article
138+
139+
File: `aspnetcore/release-notes/aspnetcore-{MAJOR_VERSION}.md`
140+
141+
### Add include directives
142+
143+
For each new include file, add a `[!INCLUDE]` directive in the appropriate
144+
product area section:
145+
146+
```
147+
[!INCLUDE[](~/release-notes/aspnetcore-{MAJOR_VERSION}/includes/{filename}.md)]
148+
```
149+
150+
### Placement rules
151+
152+
* Place new includes **after** any existing includes within each section.
153+
* Maintain a blank line before and after each `[!INCLUDE]` directive.
154+
* If a section heading exists but has no includes yet, add the include after
155+
the section's introductory sentence.
156+
157+
### Section mapping
158+
159+
Map features from the release notes to the correct section in the What's New article:
160+
161+
| Release notes area | What's New section |
162+
|---|---|
163+
| OpenAPI | `## OpenAPI` |
164+
| Authentication, Identity, Passkeys | `## Authentication and authorization` |
165+
| SignalR | `## SignalR` |
166+
| Minimal APIs | `## Minimal APIs` |
167+
| Kestrel, Servers | `## Miscellaneous` (or a dedicated section if one exists) |
168+
| Performance | `## Miscellaneous` |
169+
| Observability, OpenTelemetry | `## Miscellaneous` |
170+
| Blazor | **SKIP — handled separately** |
171+
172+
If a section doesn't exist in the What's New article but should, create it
173+
following the established pattern:
174+
175+
```markdown
176+
## Section Name
177+
178+
This section describes new features for Section Name.
179+
180+
[!INCLUDE[](~/release-notes/aspnetcore-{MAJOR_VERSION}/includes/{filename}.md)]
181+
```
182+
183+
### Update front matter on the What's New article
184+
185+
* Set `ms.date` to today's date in `MM/DD/YYYY` format.
186+
* Add `ai-usage: ai-assisted` if not already present.
187+
* Do NOT change the existing `ms.date` format — it must be MM/DD/YYYY.
188+
**Wrong**: `ms.date: 12/04/2025` when article was written on `03/10/2026`.
189+
190+
### Breaking changes section
191+
192+
* Do NOT comment out or remove the Breaking changes section.
193+
* Ensure the link uses a relative path:
194+
```markdown
195+
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.
196+
```
197+
198+
---
199+
200+
## Step 3: Validate
201+
202+
Run the validation checklist from the
203+
[whats-new-include-content-rules](../skills/whats-new-include-content-rules/SKILL.md)
204+
skill. Additionally verify:
205+
206+
- [ ] The What's New article `ms.date` is set to today's date
207+
- [ ] All `[!INCLUDE]` directives are correctly placed with blank lines around them
208+
- [ ] Section mapping matches the table above
209+
210+
---
211+
212+
## Incremental update mode
213+
214+
When invoked to check for updates (not a full new preview):
215+
216+
1. Compare the current source release notes against the existing include files.
217+
2. Report any new content, removed content, or modified content.
218+
3. Only propose changes for genuine differences — not formatting-only changes.
219+
4. If new features were added to the release notes after initial processing,
220+
create new include files following all the rules above.
221+
5. If existing feature descriptions were updated, propose edits to the
222+
corresponding include files and note what changed.

0 commit comments

Comments
 (0)