Skip to content

SKILL.md

Latest commit

 

History

History
247 lines (192 loc) · 11.8 KB

SKILL.md

File metadata and controls

247 lines (192 loc) · 11.8 KB
Raw
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 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-preview2.md (pk is an abbreviation, and preview2 combines a word with a number)
    • Correct: infer-passkey-display-name-preview-2.md (whole words, number separated by hyphen)
  • Append the preview number suffix to each filename: -preview-{N} (where {N} is the preview number, e.g., -preview-2). 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-preview-2.md
    • openapi-3-2-support-preview-2.md
    • infer-passkey-display-name-preview-2.md
    • performance-improvements-preview-2.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 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."
  • 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}.
  • 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.