|
| 1 | +--- |
| 2 | +author: wadepickett |
| 3 | +ms.author: wpickett |
| 4 | +ms.date: 07-31-2025 |
| 5 | +--- |
| 6 | + |
| 7 | +# Copilot Instructions for `dotnet/AspNetCore.Docs` |
| 8 | + |
| 9 | +## Introduction |
| 10 | +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.** |
| 11 | + |
| 12 | +## General Guidelines |
| 13 | + |
| 14 | +### Issue Handling |
| 15 | +When creating a PR for an issue: |
| 16 | +1. Read the full issue and all linked references |
| 17 | +2. 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. |
| 18 | +3. For labeled issues that have the following labels, follow these guidelines: |
| 19 | + - **new-feature:** State which version introduced the feature |
| 20 | + - **bug:** Focus on correcting technical inaccuracies |
| 21 | +4. 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. |
| 22 | +5. Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information. |
| 23 | +6. Include the folder structure of the repository, including any important directories or files that are relevant to the project. |
| 24 | + |
| 25 | +### Markdown File Naming and Organization |
| 26 | +- 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. |
| 27 | + |
| 28 | +### API References and Verification |
| 29 | + - Use `<xref:api-doc-ID>` for API cross-references. |
| 30 | + - 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. |
| 31 | + - If you cannot verify, state that explicitly in your output. |
| 32 | + |
| 33 | +### Links and References |
| 34 | +- Use relative links (for example, `../folder/file.md` or `./file.md`) when referencing files within this repository. Do not use absolute URLs or GitHub web links for internal content. |
| 35 | +- For external links, always remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.). |
| 36 | + - Example (Microsoft Learn): |
| 37 | + - Original: `https://learn.microsoft.com/en-us/aspnet/core/blazor/` |
| 38 | + - Correct: `https://learn.microsoft.com/aspnet/core/blazor/` |
| 39 | + - Example (Wikipedia): |
| 40 | + - Original: `https://en.wikipedia.org/wiki/ASP.NET_Core` |
| 41 | + - Correct: `https://wikipedia.org/wiki/ASP.NET_Core` |
| 42 | +- For Microsoft Learn links, also strip the base domain (`https://learn.microsoft.com/en-us`) so only the path remains. |
| 43 | + - Example: |
| 44 | + - Original: `https://learn.microsoft.com/en-us/aspnet/core/blazor/` |
| 45 | + - Correct: `/aspnet/core/blazor/` |
| 46 | + |
| 47 | +## Repository-Specific Guidelines |
| 48 | +- Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) |
| 49 | +- **Repository Exceptions**: |
| 50 | + - Number ordered lists as "1." for every item (don't use sequential numbers) |
| 51 | + - 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 |
| 52 | + - For Blazor's Razor components mentioned in article text, use backticks around the name of the component (example: `Counter` component) |
| 53 | + - 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) |
| 54 | + - For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included: |
| 55 | + - Metadata `ai-usage: ai-assisted` if any AI assistance was used |
| 56 | + - 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` |
| 57 | + - Metadata `ms.date: <today's 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. |
| 58 | + |
| 59 | +### Version Targeting Common Range Patterns |
| 60 | +- Fixed Range: `>= aspnetcore-7.0 <= aspnetcore-9.0` |
| 61 | +- Open Upper Bound: `>= aspnetcore-7.0` |
| 62 | +- Open Lower Bound: `<= aspnetcore-9.0` |
| 63 | +- Specific Version: `== aspnetcore-9.0` |
| 64 | + |
| 65 | +### Code Snippets |
| 66 | +- For code snippets longer than 6 lines: |
| 67 | + 1. Create a subfolder named after the document the snippet supports. |
| 68 | + 1. Create a `snippets` folder inside that subfolder. |
| 69 | + 1. For the code file: |
| 70 | + - 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. |
| 71 | + - If the snippet is version-specific: |
| 72 | + 1. Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9). |
| 73 | + 1. Place the code in a file with the correct extension inside the version subfolder. |
| 74 | + 1. Add a project file (`.csproj`) to the version subfolder targeting the matching .NET version, if necessary to run or build the snippet. |
| 75 | +- Reference snippets using triple-colon syntax: |
| 76 | + - **Use file-relative paths** for snippets located in the same file as the articles that refer to it. |
| 77 | + ``` |
| 78 | + :::code language="csharp" source="../snippets/my-doc/Program.cs"::: |
| 79 | + ``` |
| 80 | + - **Use repository root-relative paths** for shared snippets: |
| 81 | + ``` |
| 82 | + :::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/TodoDb.cs"::: |
| 83 | + ``` |
| 84 | +- For longer snippets, highlight specific lines: |
| 85 | + ``` |
| 86 | + :::code language="csharp" source="~/path/to/file.cs" range="5-10" highlight="2-3"::: |
| 87 | + ``` |
| 88 | +- Use the latest, non-preview C# coding patterns in non-preview code examples |
| 89 | +- Use the latest preview C# coding patterns in preview code examples |
| 90 | +- Use the following language code and indentation standards for markdown code blocks or the `language` attribute of code snippets: |
| 91 | +
|
| 92 | + Content of the snippet | Language code | Indentation in spaces |
| 93 | + :---: | :---: | :---: |
| 94 | + C# | csharp | 4 |
| 95 | + HTML | html | 4 |
| 96 | + CSS | css | 4 |
| 97 | + JavaScript | javascript | 2 spaces (use 4 spaces for line continuation) |
| 98 | + XML | xml | 2 |
| 99 | + JSON | json | 2 |
| 100 | + Console | console | 2 |
| 101 | + Text | - | 2 |
| 102 | +
|
| 103 | +### ASP.NET Core Specific Guidelines |
| 104 | +- Use the latest supported version for examples unless otherwise specified |
| 105 | +- Title and section header casing is sentence case (capitalize the first word and any proper nouns) |
| 106 | +- 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") |
| 107 | +- Use code style for any words that shouldn't be localized |
| 108 | +- For bullet lists, use an asterisk as the bullet marker |
| 109 | +- 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. |
| 110 | +- Lead with Microsoft-recommended approaches |
| 111 | +- Include differences between Minimal API and controller-based approaches when relevant |
| 112 | +- For middleware content and examples, use the middleware class approach |
0 commit comments