diff --git a/CopilotStore/AspNetCore.Docs/agents/breakingchange.agent.md b/CopilotStore/AspNetCore.Docs/agents/breakingchange.agent.md new file mode 100644 index 00000000..bb15f665 --- /dev/null +++ b/CopilotStore/AspNetCore.Docs/agents/breakingchange.agent.md @@ -0,0 +1,86 @@ +--- +name: breakingchange-creator +description: Agent that specializes in creating breaking change articles +--- + +You are a documentation specialist focused on breaking change articles. Focus on the following instructions: + +- Use Markdown format. +- Make content clear and concise. +- In addition to adding the new article, update any related articles that describe or use the affected feature or API to mention the new behavior. +- **Avoid gerunds** — Don't use -ing verb forms where they obscure who performs the action. Write "When you call the method..." instead of "When calling the method...". +- **Lead with reasons** — Put the reason or purpose at the beginning of a sentence. Write "To maintain compatibility, update your code" instead of "Update your code to maintain compatibility". + +## Document structure + +Start with this header (replace placeholders): + +``` +--- +title: "Breaking change: " +description: "Learn about the breaking change in where ." +ms.date: +ai-usage: ai-assisted +--- +``` + +> **Note:** +> - Use today's date in the format MM/DD/YYYY. This date cannot be earlier than 01/12/2026. +> - Do NOT include ms.custom metadata with an issue number. + +Then, include these sections in this order: + +### 1. H1 Title + +- Use the header title, but remove "Breaking change: ". + +**Intro paragraph:** +Summarize the breaking change. + +### 2. Version introduced + +- Version where change was introduced (include preview number if applicable). + +### 3. Previous behavior + +- Briefly describe past behavior using past tense. +- Start the first sentence with "Previously, ...". +- Include example code snippets if relevant. + +### 4. New behavior + +- Briefly describe new behavior using present tense. +- Start the first sentence with "Starting in , ..." +- Include example code snippets if relevant. + +### 5. Type of breaking change + +- If **behavioral change**: + `This change is a [behavioral change](/dotnet/core/compatibility/categories#behavioral-change).` +- If **source or binary incompatible**: + `This change can affect [source compatibility](/dotnet/core/compatibility/categories#source-compatibility) and/or [binary compatibility](/dotnet/core/compatibility/categories#source-compatibility).` + +### 6. Reason for change + +- Explain why the change was made. +- Include relevant links. + +### 7. Recommended action + +- Describe what users should do to adapt. +- Include code examples if helpful. + +### 8. Affected APIs + +- Bullet list of affected APIs. +- Use **xref-style links** as described in `copilot-instructions.md`. +- If none: Write "None." + +## Final steps + +- Add the new doc to the [TOC file](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/toc.yml). +- Add an entry to the index file (for example, https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/breaking-changes/11/overview.md for .NET 11 breaking changes). +- Create a pull request: + - In the description, include: `Fixes #` (replace with the correct number). + - Request review on the pull request from the person who opened the issue. +- Also check the relevant API docs, if applicable, and update them in the https://github.com/dotnet/dotnet-api-docs repo to reflect the breaking change. \ No newline at end of file diff --git a/CopilotStore/AspNetCore.Docs/agents/issue-triage-nonblazor.agent.md b/CopilotStore/AspNetCore.Docs/agents/issue-triage-nonblazor.agent.md new file mode 100644 index 00000000..4078b5fd --- /dev/null +++ b/CopilotStore/AspNetCore.Docs/agents/issue-triage-nonblazor.agent.md @@ -0,0 +1,243 @@ +--- +description: Analyzes GitHub issues for ASP.NET Core documentation, determines validity and scope, and provides structured action plans for documentation changes. +tools: + - githubread + - lexical-code-search + - semantic-code-search +ai-usage: ai-assisted +author: tdykstra +ms.author: wpickett +ms.date: 12/17/2025 +--- + +# GitHub issue preliminary analysis and action plan prompt for ASP.NET Core documentation + +## Goal +Analyze the GitHub issue and provide a **structured report** determining: +1. Whether the issue is valid and actionable. +2. Whether the issue is within scope of the articles the issue relates to, or if a new article is needed. +3. The exact documentation changes required (if applicable). +4. A clear action plan that can guide PR creation. + +The report should be suitable for posting directly in the issue discussion. + +--- + +## Analysis Steps + +### 1. Information Gathering +Collect and review: +* The **issue title, description, and all comments**. +* The **published documentation** (via the provided URL). +* The **source file(s)** in the repository. +* Any **linked issues, PRs, or external references**. +* **Environment details**: .NET version, tooling versions (VS, VS Code, CLI, EF Core, etc.). +* **Code samples or error messages** mentioned in the issue. + +### 1.5 Source File Analysis +When examining source files: +* **Provide direct GitHub permalinks** to specific lines or sections. +* **Note exact line numbers** for proposed changes. +* **Include line number ranges** in GitHub URLs using `#L-L` format. +* **Quote current content** from specific lines before proposing changes. +* **Use permalinks with commit SHA** when referencing specific versions. + +Example format for file references: +* Single line: `https://github.com/owner/repo/blob/main/file.md#L123`. +* Line range: `https://github.com/owner/repo/blob/main/file.md#L123-L145`. +* Permalink: `https://github.com/owner/repo/blob//file.md#L123`. + +### 2. Validation Criteria +Determine if the issue is: +* **In scope**: Related to ASP.NET Core documentation (not product bugs). +* **Accurate**: The reported problem genuinely exists. +* **Clear**: Sufficient information to take action. +* **Current**: Applies to supported .NET versions. + +### 3. Translation Requirements +If any content is not in English: +* Include the original text in a quote block. +* Provide complete English translation. +* Label clearly as "Original" and "Translation". + +--- + +## Output Format + +### File Naming +`-analysis-report.md` + +Provide a link to the report file, an absolute link that can be clicked on from anywhere. + +### Report Structure +Eliminate duplicate report content that may arise from running the analysis more than one time on an issue. + +#### Header (REQUIRED - Always include this community-facing notice) +```markdown +## 🤖 AI Triage Summary + +> **📌 Note to community:** This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is **not a resolution or answer** to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution! + +--- + +**This preliminary assessment report was run by:** @ +**Date:** +**Issue:** +**Model:** GitHub Copilot + +--- +``` + +#### For Valid Issues + +```markdown +# Issue Analysis: + +## ✅ Issue Validation +**Status:** Valid and actionable + +## 📋 Issue Summary + + +## 📁 Potentially Affected Files +> *These files have been identified as possibly related to this issue and may need review.* + +| File | Path | Lines | Section | +|------|------|-------|---------| +| Main article | [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) | 123-145 | "Section Heading" | +| Code sample | [`aspnetcore/path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/sample.cs#L45-L67) | 45-67 | `MethodName()` method | + +## 📝 Preliminary Change Assessment + +> *The following are initial observations for the documentation team to evaluate—not final decisions.* + +### Potential documentation Updates +**File:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) +**Location:** Lines 123-145 (after the paragraph containing "[specific anchor text]") +**Type:** [New paragraph / Note block / Code example / Replacement] + +**Current content (lines 123-125):** +```markdown +[Current text that will be replaced or followed] +``` + +**Suggested direction:** +```markdown +[Proposed documentation text here] +``` + +### Potential Code Sample Updates (if applicable) +**File:** [`sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) +**Lines:** 45-67 +**Change:** [Add/Modify/Remove] + +**Current code:** +```csharp +// Current code at specified lines +``` + +**Suggested direction:** +```csharp +// Proposed code changes +``` + +## 🎯 Suggested Action Plan +> *For documentation team review* + +1. **Review file:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md) + * Navigate to: [Line 123](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123) + * Section: "Exact Section Heading" + * Consider: [!NOTE] block with explanation + +2. **Review sample:** [`path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs) + * Navigate to: [Lines 45-67](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) + * Method: `MethodName()` + * Consider: Update to use new pattern + +## ⚠️ Review Considerations +* Verify change applies to .NET [version] +* Check if similar updates needed in related articles +* Consider adding cross-references to [related topic] + +## 🔗 References +* Published article: [URL] +* Related issue: [number] +* Microsoft Learn docs: [relevant MS docs link] +``` + +#### For Invalid Issues + +```markdown +# Issue Analysis: + +## ❓ Issue Validation +**Status:** Needs additional attention — not actionable yet as submitted +**Reason:** [Possibly out of scope / May require more information / Could be product issue / Possibly already addressed / Other - see details] + +## 📋 Preliminary Assessment +> *This is an initial analysis for team review—not a final determination.* + + + +## 💡 Possible Next Steps +> *For documentation team to consider* + +* [Close with explanation] +* [Redirect to appropriate repository] +* [Request additional information from submitter] +* [Convert to discussion] + +## 🔗 Potentially Relevant Resources +* [Link to relevant documentation] +* [Link to appropriate repository for product issues] +``` + +--- + +## Special Instructions + +### Line Number Guidelines +* **Always inspect the actual source file** to determine accurate line numbers. +* **Provide line ranges** rather than single lines when changes affect multiple lines. +* **Use GitHub's line highlighting** format in URLs (#L123 for single, #L123-L145 for range). +* **Quote the existing content** at those lines to confirm accuracy. +* **Consider context lines** - include a few lines before/after for clarity. +* **Update line numbers** if the file has changed since issue creation. + +### Content Block Usage +Only recommend using special blocks when truly appropriate, they should not be overused: +* `[!IMPORTANT]`: Security issues, breaking changes, data loss risks +* `[!WARNING]`: Common mistakes, deprecation notices +* `[!NOTE]`: Helpful clarifications, version-specific info +* `[!TIP]`: Best practices, productivity hints + +### Code Samples +* Use appropriate language identifier for syntax highlighting. +* Include necessary `using` statements or imports. +* Add comments for complex logic. +* Ensure samples are complete and runnable. + +### Scope Boundaries +**DO:** +* Focus on documentation clarity and accuracy. +* Address missing information. +* Fix technical inaccuracies. +* Improve code samples. + +**DON'T:** +* Attempt to fix product bugs through documentation. +* Make architectural recommendations. +* Add opinions or preferences. +* Modify unrelated sections. + +## Issue labels +* Upon completion of the report, set the `ai-reviewed-issue-reported-action-plan` label for the issue. + +### Common Issue Types +1. **Missing information**: Add clarifying content +2. **Outdated content**: Update to current version +3. **Broken samples**: Fix or replace code +4. **Unclear instructions**: Rewrite for clarity +5. **Missing prerequisites**: Add setup steps + +--- diff --git a/CopilotStore/AspNetCore.Docs/agents/whats-new-from-release-notes.agent.md b/CopilotStore/AspNetCore.Docs/agents/whats-new-from-release-notes.agent.md new file mode 100644 index 00000000..b9191000 --- /dev/null +++ b/CopilotStore/AspNetCore.Docs/agents/whats-new-from-release-notes.agent.md @@ -0,0 +1,218 @@ +--- +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. +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 {MAJOR_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. + +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 New include 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. diff --git a/CopilotStore/AspNetCore.Docs/copilot-code-instructions.md b/CopilotStore/AspNetCore.Docs/copilot-code-instructions.md new file mode 100644 index 00000000..79330ef3 --- /dev/null +++ b/CopilotStore/AspNetCore.Docs/copilot-code-instructions.md @@ -0,0 +1,108 @@ +--- +author: tdykstra +ms.author: wpickett +ms.date: 09-22-2025 +--- + +# Copilot Code Instructions for `dotnet/AspNetCore.Docs` + +## Introduction +This document contains code-specific instructions for GitHub Copilot when assisting with the `dotnet/AspNetCore.Docs` repository. For general instructions and documentation guidelines, please refer to the [copilot-instructions.md](./copilot-instructions.md) file. + +## Code-Related Guidelines + +### 1. Code Snippets +- [ ] For code snippets longer than 6 lines: + - [ ] Create a subfolder named after the document the snippet supports. + - [ ] Create a `snippets` folder inside that subfolder. + - [ ] For the code file: + - [ ] If the snippet is not version-specific, place the code in a file with the appropriate extension (for example, `.cs` for C#) in the `snippets` folder. + - [ ] If the snippet is version-specific: + - [ ] Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9). + - [ ] Place the code in a file with the correct extension inside the version subfolder. + - [ ] Add a project file (`.csproj`) to the version subfolder targeting the matching .NET version, if necessary to run or build the snippet. +- [ ] Reference snippets using triple-colon syntax: + - [ ] **Use file-relative paths** for snippets located in the same file as the articles that refer to it. + ``` + :::code language="csharp" source="../snippets/my-doc/Program.cs"::: + ``` + - [ ] **Use repository root-relative paths** for shared snippets: + ``` + :::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/TodoDb.cs"::: + ``` +- [ ] For longer snippets, highlight specific lines: + ``` + :::code language="csharp" source="~/path/to/file.cs" range="5-10" highlight="2-3"::: + ``` +- [ ] Use the latest, non-preview C# coding patterns in non-preview code examples +- [ ] Use the latest preview C# coding patterns in preview code examples +- [ ] Use the following language code and indentation standards for markdown code blocks or the `language` attribute of code snippets: + + Content of the snippet | Language code | Indentation in spaces + :--------------------: | :-----------: | :-------------------: + C# | csharp | 4 + HTML | html | 4 + CSS | css | 4 + JavaScript | javascript | 2 spaces (use 4 spaces for line continuation) + XML | xml | 2 + JSON | json | 2 + Console | console | 2 + Text | - | 2 + +- [ ] Code Snippet Folder Structure Requirements: + - [ ] For code snippets longer than 6 lines, create proper folder structure: article-name/snippets/version/filename.cs (e.g., cookie/snippets/6.0/Program.cs) + - [ ] Create version-specific subfolders: 3.x, 6.0, 8.0, 9.0, etc. + - [ ] Use file-relative paths for snippets in same article folder + - [ ] Use repository root-relative paths (~/) for shared snippets +- [ ] Code Snippet Markers in .cs Files - CRITICAL: + - [ ] NEVER use #region snippet_name and #endregion syntax in .cs files + - [ ] ALWAYS use // and // format (all lowercase) + - [ ] Examples of correct .cs file snippet markers: + ```csharp + // + var cookiePolicyOptions = new CookiePolicyOptions + { + MinimumSameSitePolicy = SameSiteMode.Strict, + }; + app.UseCookiePolicy(cookiePolicyOptions); + // + ``` + - [ ] INCORRECT format to avoid: + ```csharp + #region snippet_policy + // code here + #endregion + ``` +- [ ] Code Comments and Localization: + - [ ] NEVER add explanatory code comments like `// Configure cookie policy options` in .cs snippet files + - [ ] NEVER add comments like `// Add Cookie Policy Middleware` - these prevent proper localization + - [ ] Rely on markdown prose before/after code snippets for explanations instead of inline comments + - [ ] Only keep comments that are essential to the code's functionality +- [ ] Common Syntax Errors to Avoid: + - [ ] Using `range="5-10"` instead of `id="snippet_name"` + - [ ] Using `name="snippet_name"` instead of `id="snippet_name"` + - [ ] Mixing old [!code-csharp[]] syntax with new triple-colon syntax. Use triple-colon syntax. + - [ ] Using absolute line numbers in highlight="" instead of relative to snippet + - [ ] Using #region/#endregion in .cs files instead of // format +- [ ] Version-Specific Considerations: + - [ ] Create separate snippet files for different .NET versions (3.x, 6.0, 8.0, 9.0+) + - [ ] Ensure examples use appropriate syntax for the target version + - [ ] Reference the correct version-specific snippet file in markdown + +### 2. Code Build and Testing Requirements +- [ ] Ensure all code samples build successfully against the targeted .NET version +- [ ] Include necessary using statements in code samples +- [ ] When you're assigned an issue involving code changes, after you've completed your work and the workflows (status checks) have run, ensure there are no build warnings under the OpenPublishing.Build status check +- [ ] Use `#nullable enable` in C# code samples that use nullable reference types +- [ ] For Minimal API examples, use the latest patterns including group-based routing where appropriate +- [ ] For code samples targeting preview versions: + - [ ] Clearly indicate in comments or surrounding documentation that the code targets a preview version + - [ ] Provide fallback examples for current stable versions when possible + +### 3. ASP.NET Core Code-Specific Guidelines +- [ ] Use the latest supported version for examples unless otherwise specified +- [ ] Include differences between Minimal API and controller-based approaches when relevant +- [ ] For middleware content and examples, use the middleware class approach +- [ ] Code examples should be concise and focused on demonstrating a specific concept +- [ ] Include error handling in code examples where appropriate +- [ ] Ensure all code is accessible and follows best practices for ASP.NET Core applications \ No newline at end of file diff --git a/CopilotStore/AspNetCore.Docs/copilot-instructions.md b/CopilotStore/AspNetCore.Docs/copilot-instructions.md new file mode 100644 index 00000000..273be3a8 --- /dev/null +++ b/CopilotStore/AspNetCore.Docs/copilot-instructions.md @@ -0,0 +1,168 @@ +--- +author: tdykstra +ms.author: wpickett +ms.date: 10-16-2025 +--- + +# Copilot Instructions for `dotnet/AspNetCore.Docs` + +## Introduction +This document contains general and repository-specific instructions for GitHub Copilot when assisting with the `dotnet/AspNetCore.Docs` repository. **Unless otherwise specified, all ".NET" references refer to modern .NET, not .NET Framework.** + +For code-specific guidelines, including code snippets, version targeting, and language standards, please refer to the [copilot-code-instructions.md](./copilot-code-instructions.md) file. + +## General Guidelines + +### 1. Issue Handling +When creating a PR for an issue: +* [ ] Read the full issue and all linked references +* [ ] Study code samples from linked PRs that demonstrate features in the latest .NET pre-release version (e.g., .NET 10 Preview) to ensure that guidance and documentation reflect the latest upcoming changes and best practices. +* [ ] For labeled issues that have the following labels, follow these guidelines: + * [ ] **new-feature:** State which version introduced the feature + * [ ] **bug:** Focus on correcting technical inaccuracies +* [ ] When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, ensure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced. +* [ ] Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information. +* [ ] Include the folder structure of the repository, including any important directories or files that are relevant to the project. + +### 2. Issue Discussion Analysis +When working on an issue: +* [ ] **Read the complete issue discussion** - Don't rely solely on the initial issue description +* [ ] **Prioritize maintainer guidance** - Comments from repository maintainers (especially those with "MEMBER" association) should take precedence over the original issue description +* [ ] **Look for updated analysis** - Later comments may contain revised understanding, additional context, or modified resolution approaches +* [ ] **Check for explicit instructions** - Look for phrases like "Action required by GitHub Copilot" or direct "@copilot" mentions that provide specific guidance +* [ ] **Validate your understanding** - If the discussion seems to contradict the initial issue description, follow the most recent maintainer guidance + +### 3. Markdown File Naming and Organization +* [ ] If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name. + +### 4. API References and Verification + * [ ] Use `` for API cross-references. + * [ ] The API documentation ID must be verified and sourced from the official XML documentation in dotnet-api-docs, never just infer API documentation IDs by looking for similar patterns. + * [ ] If you cannot verify, state that explicitly in your output. + +### 5. Links and References +* [ ] For cross-references to other articles within the AspNetCore.Docs repository: + * [ ] Use the xref syntax: `` + * [ ] The "target-uid" of the xref syntax is obtained from the `uid` property value in the YAML front matter of the article's markdown file + * [ ] Examples + * [ ] For a target article `uid` value of `aspnetcore/mvc/overview`, the xref cross-link is `` + * [ ] For a target article `uid` value of `blazor/index`, the xref cross-link is `` + +* [ ] For non-markdown files (files that don't have the `.md` file extension) within this repository, such as PowerShell scripts and code files: + * [ ] Use relative links with the appropriate file extension + * [ ] Example: `../build-tools/build.ps1` or `./sample.json` + +* [ ] For external links to non-Microsoft sites (MDN, W3C, etc.): + * [ ] Use absolute URLs + * [ ] Remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.) + * [ ] Example (MDN): + * [ ] Original: `https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event` + * [ ] Correct: `https://developer.mozilla.org/docs/Web/API/Element/click_event` + +* [ ] For links to GitHub repositories: + * [ ] Use the full URL path + * [ ] Example: `https://github.com/maraf/blazor-wasm-react/blob/main/blazor/Counter.razor` + * [ ] Example: `https://github.com/dotnet/blazor-samples/blob/main/10.0/BlazorWebAssemblyReact/blazor/Counter.razor` + * [ ] For other Git hosting services or non-Microsoft domains, use the full URL + * [ ] Example: `https://gitlab.com/username/repo-name` + +* [ ] For links to Microsoft Learn content in other repositories: + * [ ] Use the relative URL starting with a forward slash + * [ ] Don't include the scheme and the host (example: `https://learn.microsoft.com`) and don't include the locale (example: `en-us`) + * [ ] Example: For the target Learn website URL `https://learn.microsoft.com/en-us/dotnet/core/introduction`, use the relative URL `/dotnet/core/introduction` for the link destination + +* [ ] Never use physical .md file paths in published content + * [ ] Wrong: `../blazor/index.md` or `/aspnet/core/blazor/index.md` + * [ ] Correct: `` + * [ ] Exception: GitHub-only content (such as README files, contributing guidelines, and other repository documentation that isn't published to learn.microsoft.com) should use an absolute URL to the markdown file (`.md` file extension) + +## Repository-Specific Guidelines +* [ ] Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) + * [ ] Use contractions following the guidance in [Use contractions](https://learn.microsoft.com/en-us/style-guide/word-choice/use-contractions) +* [ ] **Repository Exceptions**: + * [ ] Number ordered lists as "1." for every item (don't use sequential numbers) + * [ ] Use backticks around content specifically for file names (`file.txt`), folders (`folder`), file paths (`folder/file.txt`), custom types (`myVariable`, `MyClass`), raw URLs in the text (`https://www.contoso.com`), URL segments (`/product/id/199`), file extensions (`.razor`), NuGet packages (`Microsoft.AspNetCore.SignalR.Client`), and code that should never be localized + * [ ] For Blazor's Razor components mentioned in article text, use backticks around the name of the component (example: `Counter` component) + * [ ] Use placeholders with braces in the format `{PLACEHOLDER NAME}` when used in URIs, code examples, and other contexts where placeholders are used. Use uppercase letters with spaces between words for the placeholder name inside the braces. + * [ ] Wrong: "Launch the app and navigate to `https://localhost:/openapi/v1.json` to view the generated OpenAPI document." + * [ ] Correct: "Launch the app and navigate to `https://localhost:{PORT}/openapi/v1.json` to view the generated OpenAPI document, where the `{PORT}` placeholder is the port." + * [ ] For any new or updated .md file, ensure the standard frontmatter (metadata) is included as specified in [Metadata for Microsoft Learn documentation.](https://learn.microsoft.com/en-us/contribute/content/metadata) + * [ ] For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included: + * [ ] Metadata `ai-usage: ai-assisted` if any AI assistance was used + * [ ] Place the title metadata first, followed by the remaining metadata lines in alphabetical order. Example: `title`, `author`, `description`, `monikerRange`, `ms.author`, `ms.custom`, `ms.date`, `uid`, `zone_pivot_groups` + * [ ] Metadata `ms.date: ` with a format of MM/DD/YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters are changed in the file. + + +### 1. Metadata and Date Requirements +* [ ] CRITICAL: Set ms.date to the actual current date in MM/DD/YYYY format. Do not infer the date based on existing dates in files. Use today's date. +* [ ] Add ai-usage: ai-assisted metadata if any AI assistance was used +* [ ] Place title metadata first, followed by remaining metadata in alphabetical order +* [ ] Update ms.date if more than 50 characters are changed in existing files + * [ ] When updating ms.date always use in the format MM/DD/YYYY. Examples: + * [ ] MM: Two digits, leading zero if needed (01-12) + * [ ] DD: Two digits, leading zero if needed (01-31) + * [ ] YYYY: Four digits (2025) + * [ ] Example: `ms.date: 08/07/2025` +### 2. Version Targeting Common Range Patterns +* [ ] Fixed Range: `>= aspnetcore-7.0 <= aspnetcore-9.0` +* [ ] Open Upper Bound: `>= aspnetcore-7.0` +* [ ] Open Lower Bound: `<= aspnetcore-9.0` +* [ ] Specific Version: `== aspnetcore-9.0` + +### 3. Handling File Redirections +* [ ] When a Markdown (.md) article file (this does not apply to includes) is deleted in a PR, create a redirection entry. +* [ ] Redirections ensure users following existing links aren't left with broken links +* [ ] To add a redirection: + * [ ] Update the `.openpublishing.redirection.json` file at the repository root + * [ ] Follow this format for new entries: + ```json + { + "source_path": "aspnetcore/path/to/deleted-file.md", + "redirect_url": "/aspnet/core/path/to/target-file", + "redirect_document_id": false + } + ``` + * [ ] Use relative URLs for redirection to pages in the `learn.microsoft.com` domain + * [ ] Example: `/aspnet/core/path/to/target-file` + * [ ] For URLs in a different domain, use absolute URLs including the domain. + * [ ] Example: `https://learn.microsoft.com/dotnet/core/introduction` + * [ ] Set `redirect_document_id` to `false` unless specifically instructed otherwise + * [ ] Maintain alphabetical order of the `source_path` entries for better organization + * [ ] Ensure proper JSON formatting with correct commas between entries +* [ ] When selecting a redirect target, choose the most relevant existing content that would serve the user's original intent +* [ ] If no direct replacement exists, redirect to a parent category page or related topic + +### 4. ASP.NET Core Specific Guidelines +* [ ] Use the latest supported version for examples unless otherwise specified +* [ ] Title and section header casing is sentence case (capitalize the first word and any proper nouns) +* [ ] Capitalization of middleware and feature names: Treat middleware and descriptive framework feature names as common (general) nouns, NOT proper nouns. Use lowercase unless a word is a true proper noun, a branded product/feature name, or a code identifier (in backticks). + * [ ] Correct: "response caching middleware", "exception handling middleware", "URL rewriting middleware" (URL is a proper adjective) + * [ ] Incorrect: "Response Caching Middleware", "Exception Handling Middleware" + * [ ] Apply only normal first-word capitalization at the start of a sentence. Do NOT capitalize interior words of a middleware name in table cells, list items, or headings. + * [ ] Reserve capitalization for the exact API type name in code style when referring to the type itself (example: the `ResponseCachingMiddleware` class). + * [ ] Hyphenate compound adjectives in a middleware name when needed to prevent adjective/name ambiguity (example: "host-filtering middleware", not "host filtering middleware"). Leave unambiguous cases unhyphenated (example: "exception handling middleware"). +* [ ] For parts of a title or section header that normally use code style in article text (backticks around the content), also use code style in the title or section header (example H1 header: "# Modify the `Program.cs` file") +* [ ] Use code style for any words that shouldn't be localized +* [ ] For bullet lists, use an asterisk as the bullet marker +* [ ] Bullet lists should have two or more entries at the same level in the list. If there is only one item under a bullet, remove its bullet marker and roll that item into its parent bullet. +* [ ] Lead with Microsoft-recommended approaches +* [ ] Include differences between Minimal API and controller-based approaches when relevant +* [ ] For middleware content and examples, use the middleware class approach + +### 5. Content Writing Guidelines +* [ ] Introductory paragraph: + * [ ] When drafting the first paragraph of any new article, or when significantly updating an existing article: + * [ ] Explain why and when the topic matters in practical ASP.NET Core development scenarios. + * [ ] Give a concise summary of what the article covers or enables, so readers know what to expect. + * [ ] When significantly updating, revise the introductory paragraph to match the new scope and content. + +### 6. PR Description Requirements +* [ ] ALWAYS include "Fixes #[issue-number]" in the PR description, at the first line of the description to link back to the original issue +* [ ] Include a clear summary of changes made +* [ ] List all files that were modified with brief descriptions + +### 7. PR review guidelines (Copilot-assigned reviews) +* [ ] Flag capitalization of middleware/feature names that use proper-noun casing and suggest lowercase per the "4. ASP.NET Core Specific Guidelines" section, except for code identifiers, proper adjectives (URL, HTTP), branded names, and words that begin a sentence, heading, or bullet. +* [ ] Flag compound adjectives in feature names that risk adjective/name ambiguity and suggest hyphenation (example: "host-filtering middleware"). +* [ ] Verify sentence-case titles/headers and the metadata/ms.date rules already defined above. + diff --git a/CopilotStore/AspNetCore.Docs/skills/whats-new-include-content-rules/SKILL.md b/CopilotStore/AspNetCore.Docs/skills/whats-new-include-content-rules/SKILL.md new file mode 100644 index 00000000..b51be1ca --- /dev/null +++ b/CopilotStore/AspNetCore.Docs/skills/whats-new-include-content-rules/SKILL.md @@ -0,0 +1,215 @@ +--- +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 + +### 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, use `` + 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 + `` 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](url)."**, not "see [link text](url) for details." + - **Wrong**: "ASP.NET Core now supports OpenAPI 3.2.0 — see [the upgrade guide](url) for details." + - **Correct**: "For more information, see [the upgrade guide](url)." +* 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 `` 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. + +--- + +## 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 + +```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.