Whats New Include Content Rules

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 using whole words only.
• Each word and number must be separated by a hyphen. Do not combine words or abbreviate them, and do not combine numbers with words.
  • Wrong: infer-pk-display-name.md (pk is an abbreviation)
  • Correct: infer-passkey-display-name.md (whole words)
• Do NOT append a preview number suffix to the filename. CRITICAL: Never add a -preview-{N} suffix. Preview version suffixes cause confusion when the same feature is updated for a later preview release, and they aren't needed. Name each file for its feature only (for example, async-validation-minimal-apis.md), and update that same file in place across preview releases.
• Examples:
  • native-otel-tracing.md
  • openapi-3-2-support.md
  • infer-passkey-display-name.md
  • performance-improvements.md

One file per feature

• Create one include file per feature or section.
• Exception — Performance: Combine all performance improvements into a single performance-improvements.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 bug fixes: The What's New article only covers new features and improvements, not bug fixes.

• 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

Content fidelity — preserve information; do not condense

The What's New article is a faithful, cumulative rendering of the source release notes. Reformat and de-duplicate, but do not summarize away information.

• Default to preserving all substantive content from the source section: every code example, every explanatory sentence, and the reasoning that connects prose to code. Transfer them into the include file.
• Never drop one of a set of parallel examples. If the source shows a pattern more than once (for example, an attribute-based example and an object-based example), keep all of them. Dropping one often removes the context that makes the others understandable.
• Keep "why," not just "what." If the source explains the rationale for a code construct (for example, why a synchronous method throws), preserve that explanation next to the code. A code sample must never be left in a state where it looks contradictory or pointless without its original explanation.
• Self-containment check: after writing each include, re-read it in isolation. If any code sample would look counterintuitive or unexplained to a reader who has not seen the source notes, restore the missing explanation or example from the source.
• You MAY combine overlapping content across previews so the cumulative article doesn't repeat itself, but only remove text that is genuinely redundant — never text that carries unique information or reasoning.
• When in doubt, keep it. Prefer transferring the source wording over rewriting it more tersely. Condensing is only acceptable when it removes literal duplication.

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 <xref:> for API references — not inline code

• Wrong: `AddOpenApi()`
• Correct: <xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A>
• Wrong: `BadHttpRequestException`
• Correct: <xref:Microsoft.AspNetCore.Http.BadHttpRequestException>
• When referencing an API type or method, use <xref:fully.qualified.name> format. The xref ID must be verified from official dotnet-api-docs, not guessed.
• If the API is brand new in this preview and no xref exists yet, link to the source code on GitHub instead and add an HTML comment <!-- TODO: Update to <xref:> once API docs are published --> so it can be updated later. 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.", not "see link text for details."
  • Wrong: "ASP.NET Core now supports OpenAPI 3.2.0 — see the upgrade guide for details."
  • Correct: "For more information, see the upgrade guide."
• 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:

• No include filename has a -preview-{N} suffix.
• Every word and number in filenames is separated by a hyphen (no abbreviations, no combined word-numbers).
• No Blazor content was included.
• No bug-fix-only content was included.
• All <xref:> 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.
• Every code example from the source section is present (none dropped).
• All parallel/paired examples from the source are retained together.
• The rationale ("why") for any non-obvious code construct is preserved next to the code.
• Each include reads correctly in isolation — no code sample looks counterintuitive without the source.
• Content removed relative to the source is limited to genuine cross-preview duplication.

PR description requirements

• The very first line of the PR description must be Fixes dotnet/AspNetCore.Docs#{ISSUE NUMBER} (where {ISSUE NUMBER} is the number of the issue this PR addresses), followed by a blank line before any other content.
• When a PR fixes multiple issues, list each issue on its own line at the top of the PR description, each using the Fixes dotnet/AspNetCore.Docs#{ISSUE NUMBER} format, followed by a blank line before any other content.
• When a PR is related to other issues but doesn't fix them, use Related: dotnet/AspNetCore.Docs#{ISSUE NUMBER} on a separate line after the Fixes line(s).
• Examples:
  • Single issue:

    Fixes dotnet/AspNetCore.Docs#10000
    
    Summary of changes...
    

  • Multiple issues fixed:

    Fixes dotnet/AspNetCore.Docs#10000
    Fixes dotnet/AspNetCore.Docs#10001
    
    Summary of changes...
    

  • Fixing one issue and related to another:

    Fixes dotnet/AspNetCore.Docs#10000
    Related: dotnet/AspNetCore.Docs#10001
    
    Summary of changes...
    

Example: Correctly formatted include file

### 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 <xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A>:

```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).
• <xref:> 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.