11---
22author : wadepickett
33ms.author : wpickett
4- ms.date : 07-24 -2025
4+ ms.date : 07-25 -2025
55---
66
77# Copilot Instructions for ` dotnet/AspNetCore.Docs `
88
99## Introduction
1010
11- This document contains 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+ This document contains 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.**
1212
13- ## General Writing Guidelines
13+ ## Repository-Specific Guidelines
1414
15- - ** Follow the [ Microsoft Writing Style Guide] ( https://learn.microsoft.com/en-us/style-guide/welcome/ ) . **
16- - Additionally for this repository :
15+ - Follow the [ Microsoft Writing Style Guide] ( https://learn.microsoft.com/en-us/style-guide/welcome/ )
16+ - ** Repository Exceptions ** :
1717 - Number ordered lists as "1." for every item (don't use sequential numbers)
1818 - Use ` code style ` specifically for file names, folders, custom types, and code that should never be localized
1919
20- ## Collaboration Guidelines
21-
22- ### Status Updates and Technical Clarification
23- - Begin responses with a concise summary of your understanding
24- - Use headers to organize complex responses
25- - Provide clear status updates for multi-step tasks
26- - Format: "** Status** : [ Working on/Completed/Need input] - [ Brief description] "
27- - List specific technical questions in numbered format when seeking clarification
28- - For ASP.NET Core version questions, always specify current assumptions
29-
30- ### Draft Documentation
31- - Mark draft content with "** DRAFT** :" prefix
32- - For complex concepts, provide simplified explanations first
33- - Use code blocks with syntax highlighting
34- - Highlight areas needing expert review with comments
35- - Ensure ms.date is set to the current date
36-
37- ### Handling Feedback and Handoffs
38- - Acknowledge technical feedback with specific references
39- - For conflicting guidance, summarize approaches and request clarification
40- - When transitioning documentation:
41- - Provide structure and scope summary
42- - List unresolved questions
43- - Reference related documentation
44- - Include version-specific considerations
45-
46- ## Verification Protocols
47-
48- When uncertain about content:
49-
50- ### API References
51- - Never guess API documentation IDs
52- - State when verification is needed
53- - Provide likely namespace and class/method name
54- - Add TODO comments when creating PRs
55-
56- ### Version Compatibility
57- - Check if feature was introduced after .NET Core 3.1
58- - Default to most compatible syntax when uncertain
59- - Add version information for new APIs
60- - Include reviewer comments when verification is needed
61-
62- ### Breaking Changes
63- Use this checklist:
64- - Changes default behavior of existing API
65- - Removes or renames public API elements
66- - Changes method signatures or return types
67- - Modifies serialization format
68- - Alters dependency requirements
69- - Changes configuration schema
70-
71- ### Always Flag for Human Review
72- - Security implications
73- - Licensing considerations
74- - Product roadmap questions
75- - Comparisons with competing technologies
76- - Political or controversial technical decisions
77-
7820## Version Targeting
7921
8022### Detection Priority Order
@@ -84,65 +26,24 @@ Use this checklist:
84264 . ** Repository Branch Context** - Consider branch where PR will be merged
85275 . ** Directory Structure** - Check for version-specific directories
8628
87- ### Content Patterns
88- - State version range in first paragraph of version-specific content
89- - Use conditional content for significant version differences
90- - Use version tables for subtle differences across versions
91- - For code examples with version ranges, use conditional compilation or separate files
92- - Begin with clear version support statements
93- - Use consistent labels for version-specific content
94-
9529### Common Range Patterns
9630- Fixed Range: ` >= aspnetcore-7.0 <= aspnetcore-9.0 `
9731- Open Upper Bound: ` >= aspnetcore-7.0 `
9832- Open Lower Bound: ` <= aspnetcore-9.0 `
9933- Specific Version: ` == aspnetcore-9.0 `
10034
101- ## Localization Guidelines
102-
103- - Keep sentences short and direct
104- - Use articles consistently
105- - Avoid ambiguous pronouns
106- - Establish and maintain a clear glossary of terms
107- - Always surround code elements with backticks (`)
108- - Explain acronyms on first use
109- - Avoid culturally-specific metaphors or examples
110- - Use international date formats (YYYY-MM-DD) in code
111- - Add sufficient comments in code to explain logic
112- - Describe UI elements by function rather than appearance
113- - Minimize text embedded in images
114- - Use standard document structures that work across languages
115-
116- ## Issue and PR Collaboration
117-
118- ### Issue Classification
119- - ** Documentation Bug:** Incorrect or outdated technical information
120- - ** Content Enhancement:** Request to expand existing documentation
121- - ** New Feature Documentation:** Documentation for newly implemented features
122- - ** Localization Issue:** Problems with translated content
123- - ** Accessibility Issue:** Content that doesn't meet accessibility standards
124-
125- ### Priority Levels
126- - ** P0 (Critical):** Incorrect information that could cause serious problems
127- - ** P1 (High):** Missing key information or incorrect examples
128- - ** P2 (Medium):** Improvements to existing documentation or minor inaccuracies
129- - ** P3 (Low):** Style improvements, typos, or enhancement requests
130-
131- ### PR Comments
132- - Always include specific file paths and line numbers in comments
133- - Clearly indicate which file each suggestion applies to
134- - For multi-file issues, list all affected files
135- - Format feedback with clear section headers (Style/Format, Technical Accuracy)
136- - For technical questions, reference specific implementation concerns
137- - When suggesting changes, distinguish between required changes and optional improvements
138-
139- ### Human-Copilot Handoff
140- Scenarios requiring human intervention:
141- - Inconsistent or conflicting technical information
142- - Political or controversial topics
143- - Legal or licensing questions
144- - Security vulnerabilities
145- - Complex architectural decisions
35+ ## API References and Verification
36+
37+ - Never guess API documentation IDs
38+ - Check if features were introduced after .NET Core 3.1
39+ - Default to most compatible syntax when uncertain
40+ - For breaking changes, check:
41+ - Changes to default behavior of existing APIs
42+ - Removed or renamed public API elements
43+ - Modified method signatures or return types
44+ - Changed serialization formats
45+ - Altered dependency requirements
46+ - Changes to configuration schema
14647
14748## Links and References
14849
@@ -169,44 +70,26 @@ Scenarios requiring human intervention:
16970 ```
17071 :::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/TodoDb.cs":::
17172 ```
172-
17373- For longer snippets, highlight specific lines:
174- -
74+ ```
75+ :::code language="csharp" source="~ /path/to/file.cs" range="5-10" highlight="2-3":::
76+ ```
17577- Use modern C# coding patterns in all examples
17678
177- ## File Naming and PRs
79+ ## ASP.NET Core Specific Guidelines
17880
179- - Name Markdown files in **lowercase with hyphens** (no spaces or underscores)
180- - **Omit** filler words like "the" or "a" from file names
181- - When reviewing PRs, check for:
182- - Technical accuracy
183- - Code consistency with latest practices
184- - Style guide adherence
185- - Valid links
186- - Proper file structure
187- - Inclusive language
81+ - Use the latest supported version for examples unless otherwise specified
82+ - Lead with Microsoft recommended approaches
83+ - Include differences between minimal API and controller-based approaches when relevant
84+ - For middleware, lead with the middleware class approach
85+ - For Blazor, clearly distinguish between Server and WebAssembly hosting models
18886
18987## Issue Handling
19088
19189When creating a PR for an issue:
192-
193- 1. **Read the full issue and all linked references**
194- - Pay special attention to linked PRs with implementation details
195-
196- 2. **Understand the specific ASP.NET Core technology**
197- - For pre-release features, study code samples from linked PRs
198- - Consider version context
199- - Examine test cases to understand intended behavior
200-
201- 3. **Special handling for labeled issues:**
90+ 1. Read the full issue and all linked references
91+ 2. Study code samples from linked PRs for pre-release features
92+ 3. For labeled issues:
20293 - **breaking-change:** Include breaking change guidance
20394 - **new-feature:** State which version introduced the feature
20495 - **bug:** Focus on correcting technical inaccuracies
205-
206- ## ASP.NET Core Specific Guidelines
207-
208- - Use the latest supported version for examples unless otherwise specified
209- - Lead with Microsoft recommended approaches
210- - Include differences between minimal API and controller-based approaches when relevant
211- - For middleware, lead with the middleware class approach
212- - For Blazor, clearly distinguish between Server and WebAssembly hosting models
0 commit comments