You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Copilot Code Instructions for `dotnet/AspNetCore.Docs`
8
+
9
+
## Introduction
10
+
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.
11
+
12
+
## Code-Related Guidelines
13
+
14
+
### 1. Code Snippets
15
+
-[ ] For code snippets longer than 6 lines:
16
+
-[ ] Create a subfolder named after the document the snippet supports.
17
+
-[ ] Create a `snippets` folder inside that subfolder.
18
+
-[ ] For the code file:
19
+
-[ ] 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.
20
+
-[ ] If the snippet is version-specific:
21
+
-[ ] Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9).
22
+
-[ ] Place the code in a file with the correct extension inside the version subfolder.
23
+
-[ ] Add a project file (`.csproj`) to the version subfolder targeting the matching .NET version, if necessary to run or build the snippet.
24
+
-[ ] Reference snippets using triple-colon syntax:
25
+
-[ ]**Use file-relative paths** for snippets located in the same file as the articles that refer to it.
- [ ] NEVER use #region snippet_name and #endregion syntax in .cs files
59
+
- [ ] ALWAYS use // <snippet_name> and // </snippet_name> format (all lowercase)
60
+
- [ ] Examples of correct .cs file snippet markers:
61
+
```csharp
62
+
// <snippet_policy>
63
+
var cookiePolicyOptions = new CookiePolicyOptions
64
+
{
65
+
MinimumSameSitePolicy = SameSiteMode.Strict,
66
+
};
67
+
app.UseCookiePolicy(cookiePolicyOptions);
68
+
// </snippet_policy>
69
+
```
70
+
- [ ] INCORRECT format to avoid:
71
+
```csharp
72
+
#region snippet_policy
73
+
// code here
74
+
#endregion
75
+
```
76
+
- [ ] Code Comments and Localization:
77
+
- [ ] NEVER add explanatory code comments like `// Configure cookie policy options` in .cs snippet files
78
+
- [ ] NEVER add comments like `// Add Cookie Policy Middleware` - these prevent proper localization
79
+
- [ ] Rely on markdown prose before/after code snippets for explanations instead of inline comments
80
+
- [ ] Only keep comments that are essential to the code's functionality
81
+
- [ ] Common Syntax Errors to Avoid:
82
+
- [ ] Using `range="5-10"` instead of `id="snippet_name"`
83
+
- [ ] Using `name="snippet_name"` instead of `id="snippet_name"`
84
+
- [ ] Mixing old [!code-csharp[]] syntax with new triple-colon syntax. Use triple-colon syntax.
85
+
- [ ] Using absolute line numbers in highlight="" instead of relative to snippet
86
+
- [ ] Using #region/#endregion in .cs files instead of // <snippet_name> format
87
+
- [ ] Version-Specific Considerations:
88
+
- [ ] Create separate snippet files for different .NET versions (3.x, 6.0, 8.0, 9.0+)
89
+
- [ ] Ensure examples use appropriate syntax for the target version
90
+
- [ ] Reference the correct version-specific snippet file in markdown
91
+
92
+
### 2. Code Build and Testing Requirements
93
+
- [ ] Ensure all code samples build successfully against the targeted .NET version
94
+
- [ ] Include necessary using statements in code samples
95
+
- [ ] 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
96
+
- [ ] Use `#nullable enable` in C# code samples that use nullable reference types
97
+
- [ ] For Minimal API examples, use the latest patterns including group-based routing where appropriate
98
+
- [ ] For code samples targeting preview versions:
99
+
- [ ] Clearly indicate in comments or surrounding documentation that the code targets a preview version
100
+
- [ ] Provide fallback examples for current stable versions when possible
101
+
102
+
### 3. ASP.NET Core Code-Specific Guidelines
103
+
- [ ] Use the latest supported version for examples unless otherwise specified
104
+
- [ ] Include differences between Minimal API and controller-based approaches when relevant
105
+
- [ ] For middleware content and examples, use the middleware class approach
106
+
- [ ] Code examples should be concise and focused on demonstrating a specific concept
107
+
- [ ] Include error handling in code examples where appropriate
108
+
- [ ] Ensure all code is accessible and follows best practices for ASP.NET Core applications
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+43-47Lines changed: 43 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,16 @@
1
1
---
2
-
author: wadepickett
2
+
author: tdykstra
3
3
ms.author: wpickett
4
-
ms.date: 08-17-2025
4
+
ms.date: 09-21-2025
5
5
---
6
6
7
7
# Copilot Instructions for `dotnet/AspNetCore.Docs`
8
8
9
9
## Introduction
10
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
11
12
+
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.
13
+
12
14
## General Guidelines
13
15
14
16
### 1. Issue Handling
@@ -22,15 +24,23 @@ When creating a PR for an issue:
22
24
-[ ] Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information.
23
25
-[ ] Include the folder structure of the repository, including any important directories or files that are relevant to the project.
24
26
25
-
### 2. Markdown File Naming and Organization
27
+
### 2. Issue Discussion Analysis
28
+
When working on an issue:
29
+
-[ ]**Read the complete issue discussion** - Don't rely solely on the initial issue description
30
+
-[ ]**Prioritize maintainer guidance** - Comments from repository maintainers (especially those with "MEMBER" association) should take precedence over the original issue description
31
+
-[ ]**Look for updated analysis** - Later comments may contain revised understanding, additional context, or modified resolution approaches
32
+
-[ ]**Check for explicit instructions** - Look for phrases like "Action required by GitHub Copilot" or direct "@copilot" mentions that provide specific guidance
33
+
-[ ]**Validate your understanding** - If the discussion seems to contradict the initial issue description, follow the most recent maintainer guidance
34
+
35
+
### 3. Markdown File Naming and Organization
26
36
-[ ] 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
37
28
-
### 3. API References and Verification
38
+
### 4. API References and Verification
29
39
-[ ] Use `<xref:api-doc-ID>` for API cross-references.
30
40
-[ ] 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
41
-[ ] If you cannot verify, state that explicitly in your output.
32
42
33
-
### 4. Links and References
43
+
### 5. Links and References
34
44
-[ ] For cross-references to other articles within the AspNetCore.Docs repository:
35
45
-[ ] Use the xref syntax: `<xref:target-uid>`
36
46
-[ ] 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
@@ -77,14 +87,25 @@ When creating a PR for an issue:
77
87
-[ ] Metadata `ai-usage: ai-assisted` if any AI assistance was used
78
88
-[ ] 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`
79
89
-[ ] 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.
80
-
81
-
### 1. Version Targeting Common Range Patterns
90
+
91
+
92
+
### 1. Metadata and Date Requirements
93
+
-[ ] 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.
94
+
-[ ] Add ai-usage: ai-assisted metadata if any AI assistance was used
95
+
-[ ] Place title metadata first, followed by remaining metadata in alphabetical order
96
+
-[ ] Update ms.date if more than 50 characters are changed in existing files
97
+
-[ ] When updating ms.date always use <today's date> in the format MM/DD/YYYY. Examples:
98
+
-[ ] MM: Two digits, leading zero if needed (01-12)
99
+
-[ ] DD: Two digits, leading zero if needed (01-31)
-[ ] When a Markdown (.md) article file (this does not apply to includes) is deleted in a PR, create a redirection entry.
89
110
-[ ] Redirections ensure users following existing links aren't left with broken links
90
111
-[ ] To add a redirection:
@@ -105,45 +126,7 @@ When creating a PR for an issue:
105
126
- [ ] Maintain alphabetical order of the `source_path` entries for better organization
106
127
- [ ] Ensure proper JSON formatting with correct commas between entries
107
128
- [ ] When selecting a redirect target, choose the most relevant existing content that would serve the user's original intent
108
-
- [ ] If no direct replacement exists, redirect to a parent category page or related topic
109
-
110
-
### 3. Code Snippets
111
-
- [ ] For code snippets longer than 6 lines:
112
-
- [ ] Create a subfolder named after the document the snippet supports.
113
-
- [ ] Create a `snippets` folder inside that subfolder.
114
-
- [ ] For the code file:
115
-
- [ ] 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.
116
-
- [ ] If the snippet is version-specific:
117
-
- [ ] Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9).
118
-
- [ ] Place the code in a file with the correct extension inside the version subfolder.
119
-
- [ ] Add a project file (`.csproj`) to the version subfolder targeting the matching .NET version, if necessary to run or build the snippet.
120
-
- [ ] Reference snippets using triple-colon syntax:
121
-
- [ ] **Use file-relative paths** for snippets located in the same file as the articles that refer to it.
0 commit comments