From 813cb171222615572c1e44ea99905f8eb1a1d36d Mon Sep 17 00:00:00 2001 From: wadepickett Date: Wed, 23 Jul 2025 22:31:21 -0700 Subject: [PATCH 01/36] Add copilot-instructions to repo --- .github/copilot-instructions.md | 614 ++++++++++++++++++++++++++++++++ 1 file changed, 614 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000000..0be0d78a152f --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,614 @@ +--- +author: wadepickett +ms.author: wpickett +ms.date: 07-23-2025 +--- + +# Copilot Instructions for `dotnet/AspNetCore.Docs` + +## Quick Command Reference for Human Users + +> - By default, Copilot follows all instructions in this document when responding +> - **Optional:** Use these commands in GitHub PR comments or issues when you want to focus on specific aspects only +> - Format: `@copilot Review PR with sections: [comma-separated section names]` +> - Example: `@copilot Review PR with sections: Code Snippets, Accessibility Considerations` +> - See [Selective Instruction Application](#selective-instruction-application) section for complete details + +## Introduction + +This document contains comprehensive instructions for GitHub Copilot to follow when assisting with the `dotnet/AspNetCore.Docs` repository. These guidelines help ensure consistent, high-quality documentation that follows Microsoft's standards and best practices. **Unless otherwise specified, all ".NET" references refer to modern .NET, not .NET Framework.** + +## General Writing and Editing Guidelines + +- **Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).** +- **Headings:** + - Use sentence case (not Title Case). + - Do not use gerunds in titles. +- **Voice & Tone:** + - Use active voice whenever possible. + - Address the reader directly (second person). + - Use a conversational tone with contractions. + - Be concise and break up long sentences. + - Use present tense for instructions and descriptions. + _Example: "The method returns a value."_ + - Do **not** use "we" or "our" for documentation authors. + - Use imperative mood for instructions. + _Example: "Call the method."_ + - Use "might" instead of "may" to indicate possibility. + - **Avoid unnecessary second-person pronouns:** + - Prefer direct statements that focus on the subject rather than addressing the reader as "you" + - Instead of "You need to navigate to the project folder," use "Navigate to the project folder, which contains the `.csproj` file" + - Instead of "When you configure routing," use "When configuring routing" + - Only use "you" when alternative phrasing would be awkward or unclear + - For action statements, use imperative mood without "you" (Example: "Add the package" rather than "You should add the package") +- **Lists and Formatting:** + - Use the Oxford comma in lists of three or more items. + - Number ordered lists as "1." for every item. + - Use bullets for unordered lists. + - Use **bold** for UI elements. + - Use `code style` for file names, folders, custom types, and other text that should never be localized. + - Write raw URLs in angle brackets. + +## Human-Copilot Collaboration + +- **Clear Communication in GitHub Conversations:** + - Begin responses with a concise summary of your understanding of the task + - Use headers (## or ###) to organize complex responses + - For ASP.NET Core technical questions, cite relevant documentation or code examples + - When multiple stakeholders are involved, address specific questions to individuals using @ mentions + +- **Status Updates in PR Comments:** + - **[To reviewer]** Provide clear status updates when working on multi-step tasks + - **[To reviewer]** Format: "**Status**: [Working on/Completed/Need input] - [Brief description]" + - **[To reviewer]** For complex documentation changes, list affected files with current status + - **[To reviewer]** Example: "**Status**: Working on middleware documentation - Completed intro and configuration sections, need input on security best practices" + +- **Requesting Technical Clarification:** + - **[To reviewer]** When documentation requirements are ambiguous, list specific technical questions + - **[To reviewer]** Format questions as numbered lists for easy reference in replies + - **[To reviewer]** For ASP.NET Core version questions, always specify the current assumption + - **[To reviewer]** Example: "1. Which authentication methods should this example cover? I'm assuming JWT and cookie authentication as these are most common." + +- **Providing Draft Documentation:** + - **[To reviewer]** Clearly mark draft content in GitHub comments with "**DRAFT**:" prefix + - **[In documentation]** For complex ASP.NET Core concepts, provide simplified explanations first, followed by technical details + - **[In documentation]** Use code blocks with syntax highlighting for all code examples + - **[To reviewer]** Highlight areas needing subject matter expert review with: + - **[In documentation]** For new features, explicitly note where example code is based on preview builds + +- **Handling Technical Feedback:** + - **[To reviewer]** Acknowledge all technical feedback with specific references + - **[To reviewer]** When implementing feedback on ASP.NET Core concepts, cite relevant documentation or API references + - **[To reviewer]** For conflicting technical guidance, summarize the different approaches and request clarification + - **[To reviewer]** Always defer to ASP.NET Core team members on implementation details for pre-release features + +- **Documentation Handoff Protocol:** + - **[To reviewer]** When transitioning draft documentation to authors, provide: + - Summary of documentation structure and scope + - List of any unresolved technical questions + - References to related documentation that may need updating + - Suggestions for additional code examples if appropriate + - Version-specific considerations, especially for cross-version compatibility + +## Verification Protocols for Uncertain Content + +When you encounter situations requiring specific knowledge that may not be in your training data: + +### API Reference Verification + +- **Never guess** at API documentation IDs for `` tags +- When uncertain about an API reference: + 1. **[To reviewer]** Explicitly state: "I need to verify the correct API reference ID for [API name]" + 2. **[To reviewer]** Provide the most likely namespace and class/method name + 3. **[To reviewer]** Suggest searching dotnet-api-docs for the correct ID + 4. **[In PR code]** If creating a PR, add a comment: `` + +### Version Compatibility Verification + +- For any code example where version compatibility isn't explicitly known: + 1. Check if the feature was introduced after .NET Core 3.1 + 2. Review the API documentation for version availability notes + 3. When uncertain, default to the most compatible syntax and: + - **[In documentation]** Add a note in the documentation stating: "This example uses syntax compatible with .NET [version] and later versions." + - **[To reviewer]** Add a comment to the PR: "" + 4. For new APIs with unknown compatibility: + - **[In documentation]** Include version information: "This API is available in .NET [known version]." + - **[To reviewer]** Add a comment to the PR: "" + +### Template Selection + +- When selecting document templates: + 1. Check repository for similar document types first + 2. Look for template files in the `.github/ISSUE_TEMPLATE/` or `docs-template` directories + 3. When uncertain: + - **[In documentation]** Use the most minimal template format that fits the content type + - **[To reviewer]** Add a comment: "" + 4. For specialized content types (migration guides, samples, tutorials), always check for existing examples + +### Breaking Change Identification + +When evaluating if a change is breaking, use this checklist approach rather than guessing: +- [ ] Changes default behavior of existing API +- [ ] Removes or renames public API elements +- [ ] Changes method signatures or return types +- [ ] Modifies serialization format +- [ ] Alters dependency requirements +- [ ] Changes configuration schema + +If ANY box would be checked: +- **[In documentation]** Include a breaking change warning box +- **[To reviewer]** Add a comment: "" + +### Questions to Flag for Human Review + +ALWAYS flag these scenarios for human review rather than guessing: +- Security implications of code examples +- Licensing considerations +- Product roadmap questions +- Comparisons with competing technologies +- Political or controversial technical decisions +- Performance claims without benchmarks + +**[To reviewer]** Use this format for flagging: "**Requires Human Review**: [specific reason] - This aspect should be verified by the ASP.NET Core team because [explanation]." + +## Version Targeting + +- **Version Range Detection - Priority Order:** + 1. **Explicit PR or Issue Instructions** - Always prioritize explicit version ranges mentioned in the current PR or issue description + - Examples: "Update for .NET 8-9 compatibility" or "Add examples for .NET 7 through 9" + + 2. **File Metadata** - Check for version specifications in YAML frontmatter + - Look for: `monikerRange:`, `ms.version`, or similar metadata fields + - Example: `monikerRange: '>= aspnetcore-7.0 <= aspnetcore-9.0'` + + 3. **Inline Moniker Tags** - Look for version range specifications using moniker tags within the document + - Examples: `::: moniker range=">= aspnetcore-7.0 <= aspnetcore-9.0"` + - Pay attention to end moniker tags (`::: moniker-end`) that might indicate nested version ranges + + 4. **Repository Branch Context** - Consider the branch where the PR will be merged + - Example: if working in a `release/8.0` branch, content likely targets .NET 8.0 + + 5. **Directory Structure** - Check if the file exists in a version-specific directory + - Example: Files under `/aspnetcore/mvc/9.0/` target .NET 9.0 + +- **Handling Version Ranges in Content:** + - **[In documentation]** Explicitly state version range in the first paragraph of a document or section with version-specific content + - Example: "This feature is available in ASP.NET Core 7.0 through 9.0." + + - **[In documentation]** Use conditional content for significant version differences within a range: + ``` + ::: moniker range=">= aspnetcore-9.0" + // .NET 9.0+ content + ::: moniker-end + + ::: moniker range=">= aspnetcore-7.0 < aspnetcore-9.0" + // .NET 7.0-8.0 content + ::: moniker-end + ``` + + - **[In documentation]** Use version tables for features with subtle differences across versions + - Example: Create a table with columns for .NET 7.0, 8.0, and 9.0 and rows for different aspects of the feature + + - **[In documentation]** For code examples with version ranges: + - Use conditional compilation with appropriate `#if` directives + - Create separate snippet files for different versions when behavior varies significantly + - Include version folders for snippets (e.g., `snippets/my-doc/7.x-9.x/` for shared examples) + - Use clear naming patterns that indicate version support (e.g., `Program.Net7-9.cs`) + +- **Version Range Documentation Patterns:** + - **[In documentation]** Begin with a clear statement of supported versions + - Example: "Starting with ASP.NET Core 7.0, with additional options in 9.0, you can..." + + - **[In documentation]** Use clear labels for version-specific content: + - "Added in ASP.NET Core 8.0:" or "Changed in 9.0:" + - For version differences within a paragraph, use parenthetical clarifications: "(In ASP.NET Core 9.0+, this behavior changes to...)" + + - **[In documentation]** For features evolving across versions: + - Document the progression clearly + - Highlight deprecation warnings for features that may change in future versions + - Use tables to show property availability across version ranges + +- **Common Version Range Patterns:** + - **Fixed Range:** `>= aspnetcore-7.0 <= aspnetcore-9.0` (7.0 through 9.0) + - **Open Upper Bound:** `>= aspnetcore-7.0` (7.0 and later) + - **Open Lower Bound:** `<= aspnetcore-9.0` (9.0 and earlier) + - **Specific Version:** `== aspnetcore-9.0` (9.0 only) + - **Exclusion:** `>= aspnetcore-7.0 != aspnetcore-8.0` (7.0 and later except 8.0) + +- **If the version range is unclear:** + - **[To reviewer]** State that the version range is not specified + - **[To reviewer]** Request clarification while providing a default assumption based on context + - **[To reviewer]** Example: "The issue doesn't specify a version range. Based on the repository structure and referenced APIs, I'm assuming this applies to ASP.NET Core 7.0 through 9.0. Please confirm if this is correct." + +## Accessibility Considerations + +- **Document Structure:** + - **[In documentation]** Use proper heading hierarchy (H1 > H2 > H3) without skipping levels + - **[In documentation]** Create descriptive headings that clearly convey the section's content + - **[In documentation]** Use HTML tables with proper header cells (``) and scope attributes for data tables + - **[In documentation]** Add a summary of complex tables in the preceding text + - **[In documentation]** For Blazor and ASP.NET Core UI component documentation, include keyboard navigation instructions + +- **Code Examples:** + - **[In documentation]** Provide text explanations before code blocks that describe their purpose + - **[In documentation]** Use descriptive variable names in code samples rather than single letters or abbreviations + - **[In documentation]** Include comments in code explaining complex logic or accessibility considerations + - **[In documentation]** For accessibility-specific examples (like ARIA attributes in Razor views), clearly explain their purpose + - **[In documentation]** When documenting UI components, include accessibility properties and their recommended values + +- **Links and Navigation:** + - **[In documentation]** Use descriptive link text that makes sense out of context (avoid "click here" or "learn more") + - **[In documentation]** For API references, include the method/class name in the link text + - **[In documentation]** When linking to external resources, indicate if they open in a new window/tab + - **[In documentation]** Ensure documentation navigation patterns are consistent across related topics + +- **Images and Visual Content:** + - **[In documentation]** Always include alternative text for images that convey their purpose and content + - **[In documentation]** For screenshots of ASP.NET Core UIs or Blazor components, describe key elements shown + - **[In documentation]** For diagrams illustrating architecture or data flow, provide text descriptions of the relationships + - **[In documentation]** For code screenshots, always include the actual code in a text code block as well + - **[In documentation]** Use high contrast and colorblind-friendly color schemes in diagrams + - **[In documentation]** Avoid using color alone to convey meaning in diagrams or screenshots + +- **Inclusive Language:** + - **[In documentation]** Use person-first language when discussing accessibility features + - **[In documentation]** Avoid ableist terminology or metaphors (e.g., "see below" or "heard from users") + - **[In documentation]** Reference assistive technologies accurately and by their current names + - **[In documentation]** When discussing keyboard navigation, use standard key naming conventions + +- **Specialized Content:** + - **[In documentation]** For documenting ASP.NET Core accessibility features: + - Include WCAG success criteria being addressed where relevant + - Provide both basic and advanced implementation examples + - Reference the accessibility standards and guidelines being followed + - Include testing approaches for the feature being documented + - **[In documentation]** For Blazor components: + - Document ARIA roles, states, and properties supported + - Include keyboard interaction patterns + - Explain focus management techniques where applicable + +- **Testing Recommendations:** + - **[In documentation]** When documenting UI components, include accessibility testing guidance + - **[In documentation]** Mention relevant tools for testing ASP.NET Core applications for accessibility + - **[In documentation]** Include examples of automated and manual testing approaches + - **[In documentation]** Document common accessibility issues to watch for in specific component types + +## Localization-Friendly Content + +- **General Principles:** + - **[In documentation]** Keep sentences short and direct to facilitate translation + - **[In documentation]** Use articles ("the", "a", "an") consistently to help machine translation + - **[In documentation]** Avoid ambiguous pronouns where the referent isn't clear + - **[In documentation]** Use consistent terminology throughout related documents + +- **Technical Terminology:** + - **[In documentation]** Establish and maintain a clear glossary of ASP.NET Core terms + - **[In documentation]** Always surround code elements with backticks (`) in markdown text + - Example: The `aspnetcore.components.navigate` metric tracks route changes + - Include all properties, classes, methods, file names, folder paths, and code fragments + - This applies to inline code references, even when brief: use `JsonOptions` not JsonOptions + - **[In documentation]** Use code formatting for all code elements to maintain consistency + - **[In documentation]** Explain acronyms on first use within each document + +- **Cultural Considerations:** + - **[In documentation]** Avoid culturally-specific metaphors or examples + - **[In documentation]** Use international date formats (YYYY-MM-DD) in code examples + - **[In documentation]** Avoid directional language assuming left-to-right reading + - **[In documentation]** Use universal examples rather than region-specific ones + +- **Code Examples:** + - **[In documentation]** Add sufficient comments to explain logic, which helps translators understand context + - **[In documentation]** Keep variable names in English as per programming conventions + - **[In documentation]** Include explanatory comments for complex regex patterns or LINQ expressions + - **[In documentation]** For configuration examples, explain each setting's purpose + +- **UI References:** + - **[In documentation]** When referring to UI elements, use descriptive text rather than relying solely on appearance + - **[In documentation]** Example: "Select **Save** button at the bottom of the form" rather than "Click the green button" + - **[In documentation]** Include UI element paths for complex navigation steps + +- **Images and Diagrams:** + - **[In documentation]** Minimize text embedded in images to reduce localization burden + - **[In documentation]** Design diagrams with space for text expansion (translations often require more space) + - **[In documentation]** For essential text in diagrams, provide text alternatives that can be localized + +- **Documentation Structure:** + - **[In documentation]** Use standard document structures that work across languages + - **[In documentation]** Implement clear heading hierarchies to maintain document organization + - **[In documentation]** Keep content modular so sections can be translated independently + - **[In documentation]** Use numbered steps for procedures to maintain clarity across languages + +## Effective Issue and PR Collaboration + +### Issue Triage Protocol + +When evaluating new issues in this repository: + +1. **Issue Classification:** + - **Documentation Bug:** Incorrect or outdated technical information + - **Content Enhancement:** Request to expand existing documentation + - **New Feature Documentation:** Documentation for newly implemented features + - **Localization Issue:** Problems with translated content + - **Accessibility Issue:** Content that doesn't meet accessibility standards + +2. **Priority Assessment:** + - **P0 (Critical):** Incorrect information that could cause serious problems for users + - **P1 (High):** Missing key information about a core feature or incorrect examples + - **P2 (Medium):** Improvements to existing documentation or minor inaccuracies + - **P3 (Low):** Style improvements, typos, or enhancement requests + +3. **Initial Response Templates:** + - **[To issue reporter]** For questions: "Thanks for your question. To help you most effectively, could you please share: [specific details needed]?" + - **[To issue reporter]** For bug reports: "I've reviewed this documentation issue. I can confirm this is [accurate/needs investigation]. I'll [action plan]." + - **[To issue reporter]** For enhancement requests: "Thank you for suggesting this enhancement. This is intended to improve the documentation by [benefit]. I'll prepare a draft PR that [specific approach]." + +### PR Comment Templates + +When providing feedback on PRs: + +1. **[To PR author]** Approval with Minor Changes: + ``` + The changes look good overall! I have a few minor suggestions to align with our documentation standards: + + ## Style and Format + - [Specific style feedback with examples] + + ## Technical Accuracy + - [Any technical concerns or questions] + + These are relatively minor - feel free to address them and merge when ready. + ``` + +2. **[To PR author]** Requesting Significant Changes: + ``` + Thank you for your contribution! There are some areas that need revision before this is ready to merge: + + ## Required Changes + - [List of must-fix issues with specific examples] + + ## Suggestions for Improvement + - [Optional enhancements that would strengthen the PR] + + Please let me know if you'd like any clarification or assistance with these changes. + ``` + +3. **[To PR author]** Technical Question Format: + ``` + I have a technical question about this implementation: + + In [file/line reference], you're documenting [feature/approach]. However, this appears to [describe concern]. + + According to [reference/standard/guidance], we should [alternative approach]. Could you clarify your implementation choice or consider updating this section? + ``` + +### PR Comment Location References + +- **[To PR author]** When commenting on a PR with multiple files, always include: + - The exact file path (e.g., `docs/core/middleware/example.md`) + - The specific line number(s) or range (e.g., `Line 42` or `Lines 42-47`) + - Code snippets showing the problematic content when appropriate + - Example format: "In `docs/core/middleware/example.md` at line 42, the API reference appears to be incorrect..." +- **[To PR author]** For multi-file issues that span across files, list all affected files with their respective line numbers +- **[To PR author]** When suggesting fixes, clearly indicate which file and location each suggestion applies to +- **[To PR author]** For GitHub web UI inline comments on specific lines, additional location references are not needed as the comment is already tied to the specific location + +### Human-Copilot Handoff Protocol + +- **Scenarios Requiring Human Intervention:** + - Inconsistent or conflicting technical information that can't be resolved through available documentation + - Political or controversial topics related to technology choices or approaches + - Legal or licensing questions beyond basic MIT/Apache guidance + - Security vulnerabilities or sensitive content disclosures + - Complex architectural decisions requiring deep ASP.NET Core team knowledge + +- **Handoff Process:** + 1. **[To reviewer]** Clearly state why human expertise is needed: "This requires team discussion because..." + 2. **[To reviewer]** Summarize what you've already determined and what remains uncertain + 3. **[To reviewer]** Provide specific questions for human reviewers to address + 4. **[To reviewer]** Suggest possible approaches while acknowledging the need for human judgment + 5. **[To reviewer]** Tag appropriate team members based on the topic area + +- **Progress Preservation:** + - **[To reviewer]** When handing off, provide a summary of completed work + - **[To reviewer]** Format partially completed work in a way that's easy to continue + - **[To reviewer]** Identify decision points clearly so humans know exactly where input is needed + +### Documentation Release Coordination + +- **[In documentation]** Preview/RC Documentation: + - Include installation instructions specific to preview packages + - Note any known limitations + +- **[In documentation]** Deprecation Documentation: + - Use consistent warning format for deprecated features + - Include timeline for removal when known + - Provide migration path with concrete examples + - Link to replacement APIs or approaches + +## Selective Instruction Application + +> **Note for human users:** The following section describes commands that can be used to selectively apply sections of the copilot-instructions.md document. This information is for human reference only; Copilot will not interpret this as an instruction to selectively apply rules unless you explicitly use the command format in your requests. + +When working with Copilot, you may want to focus on specific aspects of these instructions rather than applying all guidelines. You can use the command format below in PR comments, issue comments, or direct conversations with Copilot to specify which instruction sections should be applied. + +### Example Commands + +**Full review with all sections:** +``` +@copilot Review PR #123 +``` +or explicitly listing all sections: +``` +@copilot Review PR #123 with sections: all +``` + +**Targeted review focusing on specific aspects:** +``` +@copilot Review PR #123 with sections: Accessibility Considerations, Code Snippets, Version Targeting +``` + +**PR creation with focused guidelines:** +``` +@copilot Create a PR for issue #456 with sections: General Writing and Editing Guidelines, ASP.NET Core Specific Guidance, Code Snippets +``` + +### Available Section Names + +When selecting specific sections, use these exact names: +- General Writing and Editing Guidelines +- Human-Copilot Collaboration +- Verification Protocols for Uncertain Content +- Version Targeting +- Accessibility Considerations +- Localization-Friendly Content +- Effective Issue and PR Collaboration +- Linking and References +- Code Snippets +- Markdown File Naming +- Pull Request Review Guidelines +- Issue Handling +- ASP.NET Core Specific Guidance + +## Linking and References + +- **[In documentation]** Include links to related topics/resources where relevant. + - Use **relative links** for files within this repo. + - For learn.microsoft.com links, **remove** `https://learn.microsoft.com/en-us` from the URL. +- **[In documentation]** For APIs, use cross-references: ``. + - Use the `Value` attribute from the relevant XML doc in [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs). + - For types, get the doc ID from ``. + - For members, get it from ``. + - Omit the first two characters of the doc ID. + - Example: `` + +## Code Snippets + +- **[In documentation]** For code snippets **longer than 6 lines**: + - Place them in a separate `.cs` file in a `snippets` folder next to the Markdown file. + - Within `snippets`, create a subfolder named after the document (e.g., `my-doc/snippets/`). + - For version-specific code, include a version folder (e.g., `9.x` for .NET 9, `10.x` for .NET 10 for a path like `my-doc/snippets/9.x/`). + - Add a simple `.csproj` file targeting the appropriate .NET version in the same directory. + +- **[In documentation]** Reference snippets using the triple-colon syntax: + - **Use file-relative paths** when snippets are specific to a single doc file and would move with it: + ``` + :::code language="csharp" source="../snippets/my-doc/Program.cs"::: + ``` + This approach is better when: + - The snippet is only used by one document + - The document and its snippets would be moved together during reorganization + - The snippets folder is closely tied to the doc's location + + - **Use repository root-relative paths** with `~/` for shared snippets or standardized locations: + ``` + :::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/TodoDb.cs"::: + ``` + This approach is better when: + - The snippet is shared across multiple documents + - The snippet location is standardized and unlikely to move with any specific doc + - The snippet is in a completely different section of the repository + + - Include the version folder in the path when applicable (e.g., `9.x`, `10.x`) + - Specify the language using the `language=` parameter + +- **[In documentation]** For code snippets longer than 10 lines, highlight the specific lines that are being discussed by: + - Adding line numbers in comments or descriptive text + - Using bold formatting to emphasize specific lines in the explanatory text + - Including "focus on lines X-Y" callouts before the snippet + - Use the range syntax to highlight specific lines: + ``` + :::code language="csharp" source="~/path/to/file.cs" range="5-10" highlight="2-3"::: + ``` +- **[In documentation]** Ensure all code examples are up-to-date with the latest ASP.NET Core versions. +- **[In documentation]** Include proper XML comments for any public API code examples. +- **[In documentation]** Always use modern C# coding patterns and best practices in examples. + +## Markdown File Naming + +- **[When creating files]** Name new Markdown files in **lowercase with hyphens** (no spaces or underscores). +- **[When creating files]** **Omit** filler words like "the" or "a" from file names. + +**Example:** +- **Bad:** `The-Quick-Start-Guide.md` +- **Good:** `quick-start-guide.md` + +## Pull Request Review Guidelines + +When asked to review PRs for this repository: + +1. **[To PR author]** Verify technical accuracy of ASP.NET Core content. +2. **[To PR author]** Check code consistency with latest ASP.NET Core practices and patterns. +3. **[To PR author]** Confirm style guide adherence including heading case, voice, tone, and formatting. +4. **[To PR author]** Validate links to ensure they're formatted correctly and point to valid resources. +5. **[To PR author]** Review file structure to ensure snippets are properly organized and named. +6. **[To PR author]** Check for inclusive language and adherence to Microsoft's style guide. +7. **[To PR author]** Suggest improvements for clarity, conciseness, and technical accuracy. +8. **[To PR author]** Highlight any concerns about breaking changes or version compatibility. + +## Issue Handling + +When asked to create a PR for an issue: + +1. **Read the full issue description** and any comments for context. + - **Always check any linked references** in the issue (PRs, other issues, or external links) + - **Pay special attention to linked PRs or issues** that contain implementation details about unreleased features + - If the issue mentions "check PR #xyz for details" or similar instructions, prioritize examining that content first + - For features not yet publicly released, rely on information in linked development PRs rather than public documentation + +2. **Understand the specific ASP.NET Core technology** being documented. + - For pre-release features, study any available code samples from linked development PRs + - Consider the version context (which ASP.NET Core version the feature targets) + - Examine test cases in linked PRs to understand intended behavior + +3. **Follow these steps:** + - **[When creating PR]** Create appropriate file(s) in the correct location. + - **[When creating PR]** Adhere to all style guidelines above. + - **[When creating PR]** Include proper metadata and front matter if required. + - **[When creating PR]** Create any necessary code snippets in the appropriate snippets folder. + - **[When creating PR]** Add relevant links to other documentation. + - **[When creating PR]** Include appropriate cross-references to API documentation. + +4. **Special handling for labeled issues:** + - **[In documentation]** If labeled **breaking-change**, include directions from `.github/prompts/breaking-change.md`. + - **[In documentation]** If labeled **new-feature**, ensure documentation explicitly states which version introduced the feature. + - **[In documentation]** If labeled **bug**, focus on correcting the specific technical inaccuracy noted. + +5. **Issue Template Adherence:** + - **[When responding to issues]** For **doc-issue** template: Address version information and include reference to the original document URL + - **[When responding to issues]** For **doc-request** template: Follow the structure for new topic proposals, including TOC placement and outline + - **[When responding to issues]** For **customer-feedback** issues: Pay special attention to the Document ID and URL to maintain connection to the source document + - **[To reviewer]** Note that most document issues should be opened using the "Open a documentation issue" link at the bottom of articles + - **[When responding to issues]** Preserve all metadata fields from templates in your responses to maintain traceability + +6. **Issue Prioritization:** + **[When handling multiple issues]** Consider these factors when selecting issues to address: + - **User Impact**: Issues affecting many users or blocking scenarios + - **Documentation Completeness**: Missing critical information vs. minor improvements + - **Issue Age**: Older issues may need attention to maintain community trust + - **Prerequisites**: Some issues may depend on others being resolved first + - **Resource Requirements**: Balance quick wins with more complex tasks + +7. **Issue Resolution Criteria:** + An issue can be considered resolved when: + - **[In documentation]** The documentation accurately reflects current behavior + - **[In documentation]** All requested features or clarifications are documented + - **[In documentation]** Code examples are verified to work as described + - **[In documentation]** Appropriate cross-references to related documentation exist + - **[In documentation]** The specific concern in the issue description is explicitly addressed + + **[When closing issues]** When closing an issue: + - Summarize what was changed to address it + - Link to the PR that contains the changes + - Invite feedback if the resolution needs further refinement + +## ASP.NET Core Specific Guidance + +[In documentation] Use the latest supported version for examples unless specifically documenting version differences or the document specifies a different version. A version specified in the PR or issue description takes precedence. +[In documentation] Favor leading with the Microsoft recommended approach rather than showing all possible options side-by-side. +[In documentation] Include relevant differences between minimal API and controller-based approaches when appropriate for the scope and focus of the topic. The minimal API approach is usually the favored recommendation otherwise. +[In documentation] When documenting middleware, lead with the middleware class approach followed by its extension method registration. Only include alternative middleware implementation approaches when the scope and focus of the topic requires it. +[In documentation] For Blazor content, clearly distinguish between Server and WebAssembly hosting models. + +--- + +> **Note:** If you have questions, refer to the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) or ask in the project's discussions. \ No newline at end of file From 5e6a926f0ef11e4e73a6f4e66cb4b547bca1a102 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Wed, 23 Jul 2025 23:21:53 -0700 Subject: [PATCH 02/36] improved auth example question --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0be0d78a152f..e1e61bd8b873 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -67,7 +67,7 @@ This document contains comprehensive instructions for GitHub Copilot to follow w - **[To reviewer]** When documentation requirements are ambiguous, list specific technical questions - **[To reviewer]** Format questions as numbered lists for easy reference in replies - **[To reviewer]** For ASP.NET Core version questions, always specify the current assumption - - **[To reviewer]** Example: "1. Which authentication methods should this example cover? I'm assuming JWT and cookie authentication as these are most common." + - **[To reviewer]** Example: "1. Which authentication methods should this example cover? I'm assuming Microsoft Entra ID (formerly Azure AD) integration for cloud-native applications with .NET Aspire, ASP.NET Core Identity for traditional web applications, or JWT for dedicated API scenarios." - **Providing Draft Documentation:** - **[To reviewer]** Clearly mark draft content in GitHub comments with "**DRAFT**:" prefix From 89ce49728594b6da68e35bf00fa9f8ef5feac4b8 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Thu, 24 Jul 2025 11:33:32 -0700 Subject: [PATCH 03/36] Added rule for ms.date format --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e1e61bd8b873..d1faf6f964de 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -75,6 +75,7 @@ This document contains comprehensive instructions for GitHub Copilot to follow w - **[In documentation]** Use code blocks with syntax highlighting for all code examples - **[To reviewer]** Highlight areas needing subject matter expert review with: - **[In documentation]** For new features, explicitly note where example code is based on preview builds + - **[In documentation]** Ensure the ms.date is set to the date of the draft, not the final review date using this format: `ms.date: 07-23-2025` - **Handling Technical Feedback:** - **[To reviewer]** Acknowledge all technical feedback with specific references @@ -252,7 +253,6 @@ ALWAYS flag these scenarios for human review rather than guessing: - **Inclusive Language:** - **[In documentation]** Use person-first language when discussing accessibility features - - **[In documentation]** Avoid ableist terminology or metaphors (e.g., "see below" or "heard from users") - **[In documentation]** Reference assistive technologies accurately and by their current names - **[In documentation]** When discussing keyboard navigation, use standard key naming conventions From 00fc198f874ea7fb6feef42ed849ad8dce9cbe73 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 24 Jul 2025 18:58:16 -0700 Subject: [PATCH 04/36] Update copilot-instructions.md Slimmed down considerably removing details and duplications to writing guide. --- .github/copilot-instructions.md | 740 +++++++------------------------- 1 file changed, 157 insertions(+), 583 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d1faf6f964de..298b55797404 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,614 +1,188 @@ --- author: wadepickett ms.author: wpickett -ms.date: 07-23-2025 +ms.date: 07-24-2025 --- # Copilot Instructions for `dotnet/AspNetCore.Docs` -## Quick Command Reference for Human Users - -> - By default, Copilot follows all instructions in this document when responding -> - **Optional:** Use these commands in GitHub PR comments or issues when you want to focus on specific aspects only -> - Format: `@copilot Review PR with sections: [comma-separated section names]` -> - Example: `@copilot Review PR with sections: Code Snippets, Accessibility Considerations` -> - See [Selective Instruction Application](#selective-instruction-application) section for complete details - ## Introduction -This document contains comprehensive instructions for GitHub Copilot to follow when assisting with the `dotnet/AspNetCore.Docs` repository. These guidelines help ensure consistent, high-quality documentation that follows Microsoft's standards and best practices. **Unless otherwise specified, all ".NET" references refer to modern .NET, not .NET Framework.** +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.** -## General Writing and Editing Guidelines +## General Writing Guidelines - **Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).** -- **Headings:** - - Use sentence case (not Title Case). - - Do not use gerunds in titles. -- **Voice & Tone:** - - Use active voice whenever possible. - - Address the reader directly (second person). - - Use a conversational tone with contractions. - - Be concise and break up long sentences. - - Use present tense for instructions and descriptions. - _Example: "The method returns a value."_ - - Do **not** use "we" or "our" for documentation authors. - - Use imperative mood for instructions. - _Example: "Call the method."_ - - Use "might" instead of "may" to indicate possibility. - - **Avoid unnecessary second-person pronouns:** - - Prefer direct statements that focus on the subject rather than addressing the reader as "you" - - Instead of "You need to navigate to the project folder," use "Navigate to the project folder, which contains the `.csproj` file" - - Instead of "When you configure routing," use "When configuring routing" - - Only use "you" when alternative phrasing would be awkward or unclear - - For action statements, use imperative mood without "you" (Example: "Add the package" rather than "You should add the package") -- **Lists and Formatting:** - - Use the Oxford comma in lists of three or more items. - - Number ordered lists as "1." for every item. - - Use bullets for unordered lists. - - Use **bold** for UI elements. - - Use `code style` for file names, folders, custom types, and other text that should never be localized. - - Write raw URLs in angle brackets. - -## Human-Copilot Collaboration - -- **Clear Communication in GitHub Conversations:** - - Begin responses with a concise summary of your understanding of the task - - Use headers (## or ###) to organize complex responses - - For ASP.NET Core technical questions, cite relevant documentation or code examples - - When multiple stakeholders are involved, address specific questions to individuals using @ mentions - -- **Status Updates in PR Comments:** - - **[To reviewer]** Provide clear status updates when working on multi-step tasks - - **[To reviewer]** Format: "**Status**: [Working on/Completed/Need input] - [Brief description]" - - **[To reviewer]** For complex documentation changes, list affected files with current status - - **[To reviewer]** Example: "**Status**: Working on middleware documentation - Completed intro and configuration sections, need input on security best practices" - -- **Requesting Technical Clarification:** - - **[To reviewer]** When documentation requirements are ambiguous, list specific technical questions - - **[To reviewer]** Format questions as numbered lists for easy reference in replies - - **[To reviewer]** For ASP.NET Core version questions, always specify the current assumption - - **[To reviewer]** Example: "1. Which authentication methods should this example cover? I'm assuming Microsoft Entra ID (formerly Azure AD) integration for cloud-native applications with .NET Aspire, ASP.NET Core Identity for traditional web applications, or JWT for dedicated API scenarios." - -- **Providing Draft Documentation:** - - **[To reviewer]** Clearly mark draft content in GitHub comments with "**DRAFT**:" prefix - - **[In documentation]** For complex ASP.NET Core concepts, provide simplified explanations first, followed by technical details - - **[In documentation]** Use code blocks with syntax highlighting for all code examples - - **[To reviewer]** Highlight areas needing subject matter expert review with: - - **[In documentation]** For new features, explicitly note where example code is based on preview builds - - **[In documentation]** Ensure the ms.date is set to the date of the draft, not the final review date using this format: `ms.date: 07-23-2025` - -- **Handling Technical Feedback:** - - **[To reviewer]** Acknowledge all technical feedback with specific references - - **[To reviewer]** When implementing feedback on ASP.NET Core concepts, cite relevant documentation or API references - - **[To reviewer]** For conflicting technical guidance, summarize the different approaches and request clarification - - **[To reviewer]** Always defer to ASP.NET Core team members on implementation details for pre-release features - -- **Documentation Handoff Protocol:** - - **[To reviewer]** When transitioning draft documentation to authors, provide: - - Summary of documentation structure and scope - - List of any unresolved technical questions - - References to related documentation that may need updating - - Suggestions for additional code examples if appropriate - - Version-specific considerations, especially for cross-version compatibility - -## Verification Protocols for Uncertain Content - -When you encounter situations requiring specific knowledge that may not be in your training data: - -### API Reference Verification - -- **Never guess** at API documentation IDs for `` tags -- When uncertain about an API reference: - 1. **[To reviewer]** Explicitly state: "I need to verify the correct API reference ID for [API name]" - 2. **[To reviewer]** Provide the most likely namespace and class/method name - 3. **[To reviewer]** Suggest searching dotnet-api-docs for the correct ID - 4. **[In PR code]** If creating a PR, add a comment: `` - -### Version Compatibility Verification - -- For any code example where version compatibility isn't explicitly known: - 1. Check if the feature was introduced after .NET Core 3.1 - 2. Review the API documentation for version availability notes - 3. When uncertain, default to the most compatible syntax and: - - **[In documentation]** Add a note in the documentation stating: "This example uses syntax compatible with .NET [version] and later versions." - - **[To reviewer]** Add a comment to the PR: "" - 4. For new APIs with unknown compatibility: - - **[In documentation]** Include version information: "This API is available in .NET [known version]." - - **[To reviewer]** Add a comment to the PR: "" - -### Template Selection - -- When selecting document templates: - 1. Check repository for similar document types first - 2. Look for template files in the `.github/ISSUE_TEMPLATE/` or `docs-template` directories - 3. When uncertain: - - **[In documentation]** Use the most minimal template format that fits the content type - - **[To reviewer]** Add a comment: "" - 4. For specialized content types (migration guides, samples, tutorials), always check for existing examples - -### Breaking Change Identification - -When evaluating if a change is breaking, use this checklist approach rather than guessing: -- [ ] Changes default behavior of existing API -- [ ] Removes or renames public API elements -- [ ] Changes method signatures or return types -- [ ] Modifies serialization format -- [ ] Alters dependency requirements -- [ ] Changes configuration schema - -If ANY box would be checked: -- **[In documentation]** Include a breaking change warning box -- **[To reviewer]** Add a comment: "" - -### Questions to Flag for Human Review - -ALWAYS flag these scenarios for human review rather than guessing: -- Security implications of code examples +- Additionally for this repository: + - Number ordered lists as "1." for every item (don't use sequential numbers) + - Use `code style` specifically for file names, folders, custom types, and code that should never be localized + +## Collaboration Guidelines + +### Status Updates and Technical Clarification +- Begin responses with a concise summary of your understanding +- Use headers to organize complex responses +- Provide clear status updates for multi-step tasks +- Format: "**Status**: [Working on/Completed/Need input] - [Brief description]" +- List specific technical questions in numbered format when seeking clarification +- For ASP.NET Core version questions, always specify current assumptions + +### Draft Documentation +- Mark draft content with "**DRAFT**:" prefix +- For complex concepts, provide simplified explanations first +- Use code blocks with syntax highlighting +- Highlight areas needing expert review with comments +- Ensure ms.date is set to the current date + +### Handling Feedback and Handoffs +- Acknowledge technical feedback with specific references +- For conflicting guidance, summarize approaches and request clarification +- When transitioning documentation: + - Provide structure and scope summary + - List unresolved questions + - Reference related documentation + - Include version-specific considerations + +## Verification Protocols + +When uncertain about content: + +### API References +- Never guess API documentation IDs +- State when verification is needed +- Provide likely namespace and class/method name +- Add TODO comments when creating PRs + +### Version Compatibility +- Check if feature was introduced after .NET Core 3.1 +- Default to most compatible syntax when uncertain +- Add version information for new APIs +- Include reviewer comments when verification is needed + +### Breaking Changes +Use this checklist: +- Changes default behavior of existing API +- Removes or renames public API elements +- Changes method signatures or return types +- Modifies serialization format +- Alters dependency requirements +- Changes configuration schema + +### Always Flag for Human Review +- Security implications - Licensing considerations - Product roadmap questions - Comparisons with competing technologies - Political or controversial technical decisions - Performance claims without benchmarks -**[To reviewer]** Use this format for flagging: "**Requires Human Review**: [specific reason] - This aspect should be verified by the ASP.NET Core team because [explanation]." - ## Version Targeting -- **Version Range Detection - Priority Order:** - 1. **Explicit PR or Issue Instructions** - Always prioritize explicit version ranges mentioned in the current PR or issue description - - Examples: "Update for .NET 8-9 compatibility" or "Add examples for .NET 7 through 9" - - 2. **File Metadata** - Check for version specifications in YAML frontmatter - - Look for: `monikerRange:`, `ms.version`, or similar metadata fields - - Example: `monikerRange: '>= aspnetcore-7.0 <= aspnetcore-9.0'` - - 3. **Inline Moniker Tags** - Look for version range specifications using moniker tags within the document - - Examples: `::: moniker range=">= aspnetcore-7.0 <= aspnetcore-9.0"` - - Pay attention to end moniker tags (`::: moniker-end`) that might indicate nested version ranges - - 4. **Repository Branch Context** - Consider the branch where the PR will be merged - - Example: if working in a `release/8.0` branch, content likely targets .NET 8.0 - - 5. **Directory Structure** - Check if the file exists in a version-specific directory - - Example: Files under `/aspnetcore/mvc/9.0/` target .NET 9.0 - -- **Handling Version Ranges in Content:** - - **[In documentation]** Explicitly state version range in the first paragraph of a document or section with version-specific content - - Example: "This feature is available in ASP.NET Core 7.0 through 9.0." - - - **[In documentation]** Use conditional content for significant version differences within a range: - ``` - ::: moniker range=">= aspnetcore-9.0" - // .NET 9.0+ content - ::: moniker-end - - ::: moniker range=">= aspnetcore-7.0 < aspnetcore-9.0" - // .NET 7.0-8.0 content - ::: moniker-end - ``` - - - **[In documentation]** Use version tables for features with subtle differences across versions - - Example: Create a table with columns for .NET 7.0, 8.0, and 9.0 and rows for different aspects of the feature - - - **[In documentation]** For code examples with version ranges: - - Use conditional compilation with appropriate `#if` directives - - Create separate snippet files for different versions when behavior varies significantly - - Include version folders for snippets (e.g., `snippets/my-doc/7.x-9.x/` for shared examples) - - Use clear naming patterns that indicate version support (e.g., `Program.Net7-9.cs`) - -- **Version Range Documentation Patterns:** - - **[In documentation]** Begin with a clear statement of supported versions - - Example: "Starting with ASP.NET Core 7.0, with additional options in 9.0, you can..." - - - **[In documentation]** Use clear labels for version-specific content: - - "Added in ASP.NET Core 8.0:" or "Changed in 9.0:" - - For version differences within a paragraph, use parenthetical clarifications: "(In ASP.NET Core 9.0+, this behavior changes to...)" - - - **[In documentation]** For features evolving across versions: - - Document the progression clearly - - Highlight deprecation warnings for features that may change in future versions - - Use tables to show property availability across version ranges - -- **Common Version Range Patterns:** - - **Fixed Range:** `>= aspnetcore-7.0 <= aspnetcore-9.0` (7.0 through 9.0) - - **Open Upper Bound:** `>= aspnetcore-7.0` (7.0 and later) - - **Open Lower Bound:** `<= aspnetcore-9.0` (9.0 and earlier) - - **Specific Version:** `== aspnetcore-9.0` (9.0 only) - - **Exclusion:** `>= aspnetcore-7.0 != aspnetcore-8.0` (7.0 and later except 8.0) - -- **If the version range is unclear:** - - **[To reviewer]** State that the version range is not specified - - **[To reviewer]** Request clarification while providing a default assumption based on context - - **[To reviewer]** Example: "The issue doesn't specify a version range. Based on the repository structure and referenced APIs, I'm assuming this applies to ASP.NET Core 7.0 through 9.0. Please confirm if this is correct." - -## Accessibility Considerations - -- **Document Structure:** - - **[In documentation]** Use proper heading hierarchy (H1 > H2 > H3) without skipping levels - - **[In documentation]** Create descriptive headings that clearly convey the section's content - - **[In documentation]** Use HTML tables with proper header cells (``) and scope attributes for data tables - - **[In documentation]** Add a summary of complex tables in the preceding text - - **[In documentation]** For Blazor and ASP.NET Core UI component documentation, include keyboard navigation instructions - -- **Code Examples:** - - **[In documentation]** Provide text explanations before code blocks that describe their purpose - - **[In documentation]** Use descriptive variable names in code samples rather than single letters or abbreviations - - **[In documentation]** Include comments in code explaining complex logic or accessibility considerations - - **[In documentation]** For accessibility-specific examples (like ARIA attributes in Razor views), clearly explain their purpose - - **[In documentation]** When documenting UI components, include accessibility properties and their recommended values - -- **Links and Navigation:** - - **[In documentation]** Use descriptive link text that makes sense out of context (avoid "click here" or "learn more") - - **[In documentation]** For API references, include the method/class name in the link text - - **[In documentation]** When linking to external resources, indicate if they open in a new window/tab - - **[In documentation]** Ensure documentation navigation patterns are consistent across related topics - -- **Images and Visual Content:** - - **[In documentation]** Always include alternative text for images that convey their purpose and content - - **[In documentation]** For screenshots of ASP.NET Core UIs or Blazor components, describe key elements shown - - **[In documentation]** For diagrams illustrating architecture or data flow, provide text descriptions of the relationships - - **[In documentation]** For code screenshots, always include the actual code in a text code block as well - - **[In documentation]** Use high contrast and colorblind-friendly color schemes in diagrams - - **[In documentation]** Avoid using color alone to convey meaning in diagrams or screenshots - -- **Inclusive Language:** - - **[In documentation]** Use person-first language when discussing accessibility features - - **[In documentation]** Reference assistive technologies accurately and by their current names - - **[In documentation]** When discussing keyboard navigation, use standard key naming conventions - -- **Specialized Content:** - - **[In documentation]** For documenting ASP.NET Core accessibility features: - - Include WCAG success criteria being addressed where relevant - - Provide both basic and advanced implementation examples - - Reference the accessibility standards and guidelines being followed - - Include testing approaches for the feature being documented - - **[In documentation]** For Blazor components: - - Document ARIA roles, states, and properties supported - - Include keyboard interaction patterns - - Explain focus management techniques where applicable - -- **Testing Recommendations:** - - **[In documentation]** When documenting UI components, include accessibility testing guidance - - **[In documentation]** Mention relevant tools for testing ASP.NET Core applications for accessibility - - **[In documentation]** Include examples of automated and manual testing approaches - - **[In documentation]** Document common accessibility issues to watch for in specific component types - -## Localization-Friendly Content - -- **General Principles:** - - **[In documentation]** Keep sentences short and direct to facilitate translation - - **[In documentation]** Use articles ("the", "a", "an") consistently to help machine translation - - **[In documentation]** Avoid ambiguous pronouns where the referent isn't clear - - **[In documentation]** Use consistent terminology throughout related documents - -- **Technical Terminology:** - - **[In documentation]** Establish and maintain a clear glossary of ASP.NET Core terms - - **[In documentation]** Always surround code elements with backticks (`) in markdown text - - Example: The `aspnetcore.components.navigate` metric tracks route changes - - Include all properties, classes, methods, file names, folder paths, and code fragments - - This applies to inline code references, even when brief: use `JsonOptions` not JsonOptions - - **[In documentation]** Use code formatting for all code elements to maintain consistency - - **[In documentation]** Explain acronyms on first use within each document - -- **Cultural Considerations:** - - **[In documentation]** Avoid culturally-specific metaphors or examples - - **[In documentation]** Use international date formats (YYYY-MM-DD) in code examples - - **[In documentation]** Avoid directional language assuming left-to-right reading - - **[In documentation]** Use universal examples rather than region-specific ones - -- **Code Examples:** - - **[In documentation]** Add sufficient comments to explain logic, which helps translators understand context - - **[In documentation]** Keep variable names in English as per programming conventions - - **[In documentation]** Include explanatory comments for complex regex patterns or LINQ expressions - - **[In documentation]** For configuration examples, explain each setting's purpose - -- **UI References:** - - **[In documentation]** When referring to UI elements, use descriptive text rather than relying solely on appearance - - **[In documentation]** Example: "Select **Save** button at the bottom of the form" rather than "Click the green button" - - **[In documentation]** Include UI element paths for complex navigation steps - -- **Images and Diagrams:** - - **[In documentation]** Minimize text embedded in images to reduce localization burden - - **[In documentation]** Design diagrams with space for text expansion (translations often require more space) - - **[In documentation]** For essential text in diagrams, provide text alternatives that can be localized - -- **Documentation Structure:** - - **[In documentation]** Use standard document structures that work across languages - - **[In documentation]** Implement clear heading hierarchies to maintain document organization - - **[In documentation]** Keep content modular so sections can be translated independently - - **[In documentation]** Use numbered steps for procedures to maintain clarity across languages - -## Effective Issue and PR Collaboration - -### Issue Triage Protocol - -When evaluating new issues in this repository: - -1. **Issue Classification:** - - **Documentation Bug:** Incorrect or outdated technical information - - **Content Enhancement:** Request to expand existing documentation - - **New Feature Documentation:** Documentation for newly implemented features - - **Localization Issue:** Problems with translated content - - **Accessibility Issue:** Content that doesn't meet accessibility standards - -2. **Priority Assessment:** - - **P0 (Critical):** Incorrect information that could cause serious problems for users - - **P1 (High):** Missing key information about a core feature or incorrect examples - - **P2 (Medium):** Improvements to existing documentation or minor inaccuracies - - **P3 (Low):** Style improvements, typos, or enhancement requests - -3. **Initial Response Templates:** - - **[To issue reporter]** For questions: "Thanks for your question. To help you most effectively, could you please share: [specific details needed]?" - - **[To issue reporter]** For bug reports: "I've reviewed this documentation issue. I can confirm this is [accurate/needs investigation]. I'll [action plan]." - - **[To issue reporter]** For enhancement requests: "Thank you for suggesting this enhancement. This is intended to improve the documentation by [benefit]. I'll prepare a draft PR that [specific approach]." - -### PR Comment Templates - -When providing feedback on PRs: - -1. **[To PR author]** Approval with Minor Changes: - ``` - The changes look good overall! I have a few minor suggestions to align with our documentation standards: - - ## Style and Format - - [Specific style feedback with examples] - - ## Technical Accuracy - - [Any technical concerns or questions] - - These are relatively minor - feel free to address them and merge when ready. - ``` - -2. **[To PR author]** Requesting Significant Changes: - ``` - Thank you for your contribution! There are some areas that need revision before this is ready to merge: - - ## Required Changes - - [List of must-fix issues with specific examples] - - ## Suggestions for Improvement - - [Optional enhancements that would strengthen the PR] - - Please let me know if you'd like any clarification or assistance with these changes. - ``` - -3. **[To PR author]** Technical Question Format: - ``` - I have a technical question about this implementation: - - In [file/line reference], you're documenting [feature/approach]. However, this appears to [describe concern]. - - According to [reference/standard/guidance], we should [alternative approach]. Could you clarify your implementation choice or consider updating this section? - ``` - -### PR Comment Location References - -- **[To PR author]** When commenting on a PR with multiple files, always include: - - The exact file path (e.g., `docs/core/middleware/example.md`) - - The specific line number(s) or range (e.g., `Line 42` or `Lines 42-47`) - - Code snippets showing the problematic content when appropriate - - Example format: "In `docs/core/middleware/example.md` at line 42, the API reference appears to be incorrect..." -- **[To PR author]** For multi-file issues that span across files, list all affected files with their respective line numbers -- **[To PR author]** When suggesting fixes, clearly indicate which file and location each suggestion applies to -- **[To PR author]** For GitHub web UI inline comments on specific lines, additional location references are not needed as the comment is already tied to the specific location - -### Human-Copilot Handoff Protocol - -- **Scenarios Requiring Human Intervention:** - - Inconsistent or conflicting technical information that can't be resolved through available documentation - - Political or controversial topics related to technology choices or approaches - - Legal or licensing questions beyond basic MIT/Apache guidance - - Security vulnerabilities or sensitive content disclosures - - Complex architectural decisions requiring deep ASP.NET Core team knowledge - -- **Handoff Process:** - 1. **[To reviewer]** Clearly state why human expertise is needed: "This requires team discussion because..." - 2. **[To reviewer]** Summarize what you've already determined and what remains uncertain - 3. **[To reviewer]** Provide specific questions for human reviewers to address - 4. **[To reviewer]** Suggest possible approaches while acknowledging the need for human judgment - 5. **[To reviewer]** Tag appropriate team members based on the topic area - -- **Progress Preservation:** - - **[To reviewer]** When handing off, provide a summary of completed work - - **[To reviewer]** Format partially completed work in a way that's easy to continue - - **[To reviewer]** Identify decision points clearly so humans know exactly where input is needed - -### Documentation Release Coordination - -- **[In documentation]** Preview/RC Documentation: - - Include installation instructions specific to preview packages - - Note any known limitations - -- **[In documentation]** Deprecation Documentation: - - Use consistent warning format for deprecated features - - Include timeline for removal when known - - Provide migration path with concrete examples - - Link to replacement APIs or approaches - -## Selective Instruction Application - -> **Note for human users:** The following section describes commands that can be used to selectively apply sections of the copilot-instructions.md document. This information is for human reference only; Copilot will not interpret this as an instruction to selectively apply rules unless you explicitly use the command format in your requests. - -When working with Copilot, you may want to focus on specific aspects of these instructions rather than applying all guidelines. You can use the command format below in PR comments, issue comments, or direct conversations with Copilot to specify which instruction sections should be applied. - -### Example Commands - -**Full review with all sections:** -``` -@copilot Review PR #123 -``` -or explicitly listing all sections: -``` -@copilot Review PR #123 with sections: all -``` - -**Targeted review focusing on specific aspects:** -``` -@copilot Review PR #123 with sections: Accessibility Considerations, Code Snippets, Version Targeting -``` - -**PR creation with focused guidelines:** -``` -@copilot Create a PR for issue #456 with sections: General Writing and Editing Guidelines, ASP.NET Core Specific Guidance, Code Snippets -``` - -### Available Section Names - -When selecting specific sections, use these exact names: -- General Writing and Editing Guidelines -- Human-Copilot Collaboration -- Verification Protocols for Uncertain Content -- Version Targeting -- Accessibility Considerations -- Localization-Friendly Content -- Effective Issue and PR Collaboration -- Linking and References -- Code Snippets -- Markdown File Naming -- Pull Request Review Guidelines -- Issue Handling -- ASP.NET Core Specific Guidance - -## Linking and References - -- **[In documentation]** Include links to related topics/resources where relevant. - - Use **relative links** for files within this repo. - - For learn.microsoft.com links, **remove** `https://learn.microsoft.com/en-us` from the URL. -- **[In documentation]** For APIs, use cross-references: ``. - - Use the `Value` attribute from the relevant XML doc in [dotnet-api-docs](https://github.com/dotnet/dotnet-api-docs). - - For types, get the doc ID from ``. - - For members, get it from ``. - - Omit the first two characters of the doc ID. - - Example: `` +### Detection Priority Order +1. **Explicit PR/Issue Instructions** - Prioritize explicit version ranges mentioned +2. **File Metadata** - Check YAML frontmatter for specifications +3. **Inline Moniker Tags** - Look for version range specifications +4. **Repository Branch Context** - Consider branch where PR will be merged +5. **Directory Structure** - Check for version-specific directories + +### Content Patterns +- State version range in first paragraph of version-specific content +- Use conditional content for significant version differences +- Use version tables for subtle differences across versions +- For code examples with version ranges, use conditional compilation or separate files +- Begin with clear version support statements +- Use consistent labels for version-specific content + +### 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` + +## Accessibility Guidelines + +- Use proper heading hierarchy without skipping levels +- Create descriptive headings that convey section content +- Use HTML tables with proper header cells and scope attributes +- Include keyboard navigation instructions for UI components +- Provide text explanations before code blocks +- Use descriptive variable names in code samples +- Use descriptive link text that makes sense out of context +- Include alt text for images that conveys purpose and content +- Use person-first language when discussing accessibility features +- Document ARIA roles, states, and properties for components +- Include accessibility testing guidance + +## Localization Guidelines + +- Keep sentences short and direct +- Use articles consistently +- Avoid ambiguous pronouns +- Establish and maintain a clear glossary of terms +- Always surround code elements with backticks (`) +- Explain acronyms on first use +- Avoid culturally-specific metaphors or examples +- Use international date formats (YYYY-MM-DD) in code +- Add sufficient comments in code to explain logic +- Describe UI elements by function rather than appearance +- Minimize text embedded in images +- Use standard document structures that work across languages + +## Issue and PR Collaboration + +### Issue Classification +- **Documentation Bug:** Incorrect or outdated technical information +- **Content Enhancement:** Request to expand existing documentation +- **New Feature Documentation:** Documentation for newly implemented features +- **Localization Issue:** Problems with translated content +- **Accessibility Issue:** Content that doesn't meet accessibility standards + +### Priority Levels +- **P0 (Critical):** Incorrect information that could cause serious problems +- **P1 (High):** Missing key information or incorrect examples +- **P2 (Medium):** Improvements to existing documentation or minor inaccuracies +- **P3 (Low):** Style improvements, typos, or enhancement requests + +### PR Comments +- Always include specific file paths and line numbers in comments +- Clearly indicate which file each suggestion applies to +- For multi-file issues, list all affected files +- Format feedback with clear section headers (Style/Format, Technical Accuracy) +- For technical questions, reference specific implementation concerns +- When suggesting changes, distinguish between required changes and optional improvements + +### Human-Copilot Handoff +Scenarios requiring human intervention: +- Inconsistent or conflicting technical information +- Political or controversial topics +- Legal or licensing questions +- Security vulnerabilities +- Complex architectural decisions + +## Links and References + +- Use **relative links** for files within this repo +- For learn.microsoft.com links, **remove** `https://learn.microsoft.com/en-us` from URLs +- Use cross-references for APIs: `` +- Get doc ID from the relevant XML doc in dotnet-api-docs +- Omit first two characters of the doc ID ## Code Snippets -- **[In documentation]** For code snippets **longer than 6 lines**: - - Place them in a separate `.cs` file in a `snippets` folder next to the Markdown file. - - Within `snippets`, create a subfolder named after the document (e.g., `my-doc/snippets/`). - - For version-specific code, include a version folder (e.g., `9.x` for .NET 9, `10.x` for .NET 10 for a path like `my-doc/snippets/9.x/`). - - Add a simple `.csproj` file targeting the appropriate .NET version in the same directory. +- For snippets **longer than 6 lines**: + - Place in separate `.cs` file in a `snippets` folder next to the Markdown file + - Create a subfolder named after the document + - For version-specific code, include a version folder + - Add a simple `.csproj` file targeting the appropriate .NET version -- **[In documentation]** Reference snippets using the triple-colon syntax: - - **Use file-relative paths** when snippets are specific to a single doc file and would move with it: +- Reference snippets using triple-colon syntax: + - **Use file-relative paths** for snippets specific to a single doc file: ``` :::code language="csharp" source="../snippets/my-doc/Program.cs"::: ``` - This approach is better when: - - The snippet is only used by one document - - The document and its snippets would be moved together during reorganization - - The snippets folder is closely tied to the doc's location - - - **Use repository root-relative paths** with `~/` for shared snippets or standardized locations: + - **Use repository root-relative paths** for shared snippets: ``` :::code language="csharp" source="~/tutorials/min-web-api/samples/9.x/todoGroup/TodoDb.cs"::: ``` - This approach is better when: - - The snippet is shared across multiple documents - - The snippet location is standardized and unlikely to move with any specific doc - - The snippet is in a completely different section of the repository - - - Include the version folder in the path when applicable (e.g., `9.x`, `10.x`) - - Specify the language using the `language=` parameter - -- **[In documentation]** For code snippets longer than 10 lines, highlight the specific lines that are being discussed by: - - Adding line numbers in comments or descriptive text - - Using bold formatting to emphasize specific lines in the explanatory text - - Including "focus on lines X-Y" callouts before the snippet - - Use the range syntax to highlight specific lines: - ``` - :::code language="csharp" source="~/path/to/file.cs" range="5-10" highlight="2-3"::: - ``` -- **[In documentation]** Ensure all code examples are up-to-date with the latest ASP.NET Core versions. -- **[In documentation]** Include proper XML comments for any public API code examples. -- **[In documentation]** Always use modern C# coding patterns and best practices in examples. - -## Markdown File Naming - -- **[When creating files]** Name new Markdown files in **lowercase with hyphens** (no spaces or underscores). -- **[When creating files]** **Omit** filler words like "the" or "a" from file names. - -**Example:** -- **Bad:** `The-Quick-Start-Guide.md` -- **Good:** `quick-start-guide.md` - -## Pull Request Review Guidelines - -When asked to review PRs for this repository: - -1. **[To PR author]** Verify technical accuracy of ASP.NET Core content. -2. **[To PR author]** Check code consistency with latest ASP.NET Core practices and patterns. -3. **[To PR author]** Confirm style guide adherence including heading case, voice, tone, and formatting. -4. **[To PR author]** Validate links to ensure they're formatted correctly and point to valid resources. -5. **[To PR author]** Review file structure to ensure snippets are properly organized and named. -6. **[To PR author]** Check for inclusive language and adherence to Microsoft's style guide. -7. **[To PR author]** Suggest improvements for clarity, conciseness, and technical accuracy. -8. **[To PR author]** Highlight any concerns about breaking changes or version compatibility. - -## Issue Handling - -When asked to create a PR for an issue: - -1. **Read the full issue description** and any comments for context. - - **Always check any linked references** in the issue (PRs, other issues, or external links) - - **Pay special attention to linked PRs or issues** that contain implementation details about unreleased features - - If the issue mentions "check PR #xyz for details" or similar instructions, prioritize examining that content first - - For features not yet publicly released, rely on information in linked development PRs rather than public documentation - -2. **Understand the specific ASP.NET Core technology** being documented. - - For pre-release features, study any available code samples from linked development PRs - - Consider the version context (which ASP.NET Core version the feature targets) - - Examine test cases in linked PRs to understand intended behavior - -3. **Follow these steps:** - - **[When creating PR]** Create appropriate file(s) in the correct location. - - **[When creating PR]** Adhere to all style guidelines above. - - **[When creating PR]** Include proper metadata and front matter if required. - - **[When creating PR]** Create any necessary code snippets in the appropriate snippets folder. - - **[When creating PR]** Add relevant links to other documentation. - - **[When creating PR]** Include appropriate cross-references to API documentation. - -4. **Special handling for labeled issues:** - - **[In documentation]** If labeled **breaking-change**, include directions from `.github/prompts/breaking-change.md`. - - **[In documentation]** If labeled **new-feature**, ensure documentation explicitly states which version introduced the feature. - - **[In documentation]** If labeled **bug**, focus on correcting the specific technical inaccuracy noted. - -5. **Issue Template Adherence:** - - **[When responding to issues]** For **doc-issue** template: Address version information and include reference to the original document URL - - **[When responding to issues]** For **doc-request** template: Follow the structure for new topic proposals, including TOC placement and outline - - **[When responding to issues]** For **customer-feedback** issues: Pay special attention to the Document ID and URL to maintain connection to the source document - - **[To reviewer]** Note that most document issues should be opened using the "Open a documentation issue" link at the bottom of articles - - **[When responding to issues]** Preserve all metadata fields from templates in your responses to maintain traceability - -6. **Issue Prioritization:** - **[When handling multiple issues]** Consider these factors when selecting issues to address: - - **User Impact**: Issues affecting many users or blocking scenarios - - **Documentation Completeness**: Missing critical information vs. minor improvements - - **Issue Age**: Older issues may need attention to maintain community trust - - **Prerequisites**: Some issues may depend on others being resolved first - - **Resource Requirements**: Balance quick wins with more complex tasks - -7. **Issue Resolution Criteria:** - An issue can be considered resolved when: - - **[In documentation]** The documentation accurately reflects current behavior - - **[In documentation]** All requested features or clarifications are documented - - **[In documentation]** Code examples are verified to work as described - - **[In documentation]** Appropriate cross-references to related documentation exist - - **[In documentation]** The specific concern in the issue description is explicitly addressed - - **[When closing issues]** When closing an issue: - - Summarize what was changed to address it - - Link to the PR that contains the changes - - Invite feedback if the resolution needs further refinement - -## ASP.NET Core Specific Guidance - -[In documentation] Use the latest supported version for examples unless specifically documenting version differences or the document specifies a different version. A version specified in the PR or issue description takes precedence. -[In documentation] Favor leading with the Microsoft recommended approach rather than showing all possible options side-by-side. -[In documentation] Include relevant differences between minimal API and controller-based approaches when appropriate for the scope and focus of the topic. The minimal API approach is usually the favored recommendation otherwise. -[In documentation] When documenting middleware, lead with the middleware class approach followed by its extension method registration. Only include alternative middleware implementation approaches when the scope and focus of the topic requires it. -[In documentation] For Blazor content, clearly distinguish between Server and WebAssembly hosting models. - ---- -> **Note:** If you have questions, refer to the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) or ask in the project's discussions. \ No newline at end of file +- For longer snippets, highlight specific lines: From 8d604702d524d9d6a6e45148752fe5f3f45a8429 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 24 Jul 2025 19:05:40 -0700 Subject: [PATCH 05/36] Update copilot-instructions.md Added back in a section that was truncated. --- .github/copilot-instructions.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 298b55797404..844581d24c4b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -74,7 +74,6 @@ Use this checklist: - Product roadmap questions - Comparisons with competing technologies - Political or controversial technical decisions -- Performance claims without benchmarks ## Version Targeting @@ -99,20 +98,6 @@ Use this checklist: - Open Lower Bound: `<= aspnetcore-9.0` - Specific Version: `== aspnetcore-9.0` -## Accessibility Guidelines - -- Use proper heading hierarchy without skipping levels -- Create descriptive headings that convey section content -- Use HTML tables with proper header cells and scope attributes -- Include keyboard navigation instructions for UI components -- Provide text explanations before code blocks -- Use descriptive variable names in code samples -- Use descriptive link text that makes sense out of context -- Include alt text for images that conveys purpose and content -- Use person-first language when discussing accessibility features -- Document ARIA roles, states, and properties for components -- Include accessibility testing guidance - ## Localization Guidelines - Keep sentences short and direct From 23314f7b58cc371f5144d168f13db60f84192689 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 24 Jul 2025 19:20:47 -0700 Subject: [PATCH 06/36] Update copilot-instructions.md Added truncated last section back in. --- .github/copilot-instructions.md | 39 +++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 844581d24c4b..af6914fd283e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -171,3 +171,42 @@ Scenarios requiring human intervention: ``` - For longer snippets, highlight specific lines: +- +- Use modern C# coding patterns in all examples + +## File Naming and PRs + +- Name Markdown files in **lowercase with hyphens** (no spaces or underscores) +- **Omit** filler words like "the" or "a" from file names +- When reviewing PRs, check for: +- Technical accuracy +- Code consistency with latest practices +- Style guide adherence +- Valid links +- Proper file structure +- Inclusive language + +## Issue Handling + +When creating a PR for an issue: + +1. **Read the full issue and all linked references** + - Pay special attention to linked PRs with implementation details + +2. **Understand the specific ASP.NET Core technology** + - For pre-release features, study code samples from linked PRs + - Consider version context + - Examine test cases to understand intended behavior + +3. **Special handling for labeled issues:** + - **breaking-change:** Include breaking change guidance + - **new-feature:** State which version introduced the feature + - **bug:** Focus on correcting technical inaccuracies + +## ASP.NET Core Specific Guidelines + +- Use the latest supported version for examples unless otherwise specified +- Lead with Microsoft recommended approaches +- Include differences between minimal API and controller-based approaches when relevant +- For middleware, lead with the middleware class approach +- For Blazor, clearly distinguish between Server and WebAssembly hosting models From ebe7aff556b4b4d65e43bf662a1509bd0f0336db Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 24 Jul 2025 19:37:07 -0700 Subject: [PATCH 07/36] Update copilot-instructions.md Fixed truncating issue. --- .github/copilot-instructions.md | 175 ++++++-------------------------- 1 file changed, 29 insertions(+), 146 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index af6914fd283e..859855d993a7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,80 +1,22 @@ --- author: wadepickett ms.author: wpickett -ms.date: 07-24-2025 +ms.date: 07-25-2025 --- # Copilot Instructions for `dotnet/AspNetCore.Docs` ## Introduction -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.** +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.** -## General Writing Guidelines +## Repository-Specific Guidelines -- **Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).** -- Additionally for this repository: +- Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) +- **Repository Exceptions**: - Number ordered lists as "1." for every item (don't use sequential numbers) - Use `code style` specifically for file names, folders, custom types, and code that should never be localized -## Collaboration Guidelines - -### Status Updates and Technical Clarification -- Begin responses with a concise summary of your understanding -- Use headers to organize complex responses -- Provide clear status updates for multi-step tasks -- Format: "**Status**: [Working on/Completed/Need input] - [Brief description]" -- List specific technical questions in numbered format when seeking clarification -- For ASP.NET Core version questions, always specify current assumptions - -### Draft Documentation -- Mark draft content with "**DRAFT**:" prefix -- For complex concepts, provide simplified explanations first -- Use code blocks with syntax highlighting -- Highlight areas needing expert review with comments -- Ensure ms.date is set to the current date - -### Handling Feedback and Handoffs -- Acknowledge technical feedback with specific references -- For conflicting guidance, summarize approaches and request clarification -- When transitioning documentation: - - Provide structure and scope summary - - List unresolved questions - - Reference related documentation - - Include version-specific considerations - -## Verification Protocols - -When uncertain about content: - -### API References -- Never guess API documentation IDs -- State when verification is needed -- Provide likely namespace and class/method name -- Add TODO comments when creating PRs - -### Version Compatibility -- Check if feature was introduced after .NET Core 3.1 -- Default to most compatible syntax when uncertain -- Add version information for new APIs -- Include reviewer comments when verification is needed - -### Breaking Changes -Use this checklist: -- Changes default behavior of existing API -- Removes or renames public API elements -- Changes method signatures or return types -- Modifies serialization format -- Alters dependency requirements -- Changes configuration schema - -### Always Flag for Human Review -- Security implications -- Licensing considerations -- Product roadmap questions -- Comparisons with competing technologies -- Political or controversial technical decisions - ## Version Targeting ### Detection Priority Order @@ -84,65 +26,24 @@ Use this checklist: 4. **Repository Branch Context** - Consider branch where PR will be merged 5. **Directory Structure** - Check for version-specific directories -### Content Patterns -- State version range in first paragraph of version-specific content -- Use conditional content for significant version differences -- Use version tables for subtle differences across versions -- For code examples with version ranges, use conditional compilation or separate files -- Begin with clear version support statements -- Use consistent labels for version-specific content - ### 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` -## Localization Guidelines - -- Keep sentences short and direct -- Use articles consistently -- Avoid ambiguous pronouns -- Establish and maintain a clear glossary of terms -- Always surround code elements with backticks (`) -- Explain acronyms on first use -- Avoid culturally-specific metaphors or examples -- Use international date formats (YYYY-MM-DD) in code -- Add sufficient comments in code to explain logic -- Describe UI elements by function rather than appearance -- Minimize text embedded in images -- Use standard document structures that work across languages - -## Issue and PR Collaboration - -### Issue Classification -- **Documentation Bug:** Incorrect or outdated technical information -- **Content Enhancement:** Request to expand existing documentation -- **New Feature Documentation:** Documentation for newly implemented features -- **Localization Issue:** Problems with translated content -- **Accessibility Issue:** Content that doesn't meet accessibility standards - -### Priority Levels -- **P0 (Critical):** Incorrect information that could cause serious problems -- **P1 (High):** Missing key information or incorrect examples -- **P2 (Medium):** Improvements to existing documentation or minor inaccuracies -- **P3 (Low):** Style improvements, typos, or enhancement requests - -### PR Comments -- Always include specific file paths and line numbers in comments -- Clearly indicate which file each suggestion applies to -- For multi-file issues, list all affected files -- Format feedback with clear section headers (Style/Format, Technical Accuracy) -- For technical questions, reference specific implementation concerns -- When suggesting changes, distinguish between required changes and optional improvements - -### Human-Copilot Handoff -Scenarios requiring human intervention: -- Inconsistent or conflicting technical information -- Political or controversial topics -- Legal or licensing questions -- Security vulnerabilities -- Complex architectural decisions +## API References and Verification + +- Never guess API documentation IDs +- Check if features were introduced after .NET Core 3.1 +- Default to most compatible syntax when uncertain +- For breaking changes, check: + - Changes to default behavior of existing APIs + - Removed or renamed public API elements + - Modified method signatures or return types + - Changed serialization formats + - Altered dependency requirements + - Changes to configuration schema ## Links and References @@ -169,44 +70,26 @@ Scenarios requiring human intervention: ``` :::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 modern C# coding patterns in all examples -## File Naming and PRs +## ASP.NET Core Specific Guidelines -- Name Markdown files in **lowercase with hyphens** (no spaces or underscores) -- **Omit** filler words like "the" or "a" from file names -- When reviewing PRs, check for: -- Technical accuracy -- Code consistency with latest practices -- Style guide adherence -- Valid links -- Proper file structure -- Inclusive language +- Use the latest supported version for examples unless otherwise specified +- Lead with Microsoft recommended approaches +- Include differences between minimal API and controller-based approaches when relevant +- For middleware, lead with the middleware class approach +- For Blazor, clearly distinguish between Server and WebAssembly hosting models ## Issue Handling When creating a PR for an issue: - -1. **Read the full issue and all linked references** - - Pay special attention to linked PRs with implementation details - -2. **Understand the specific ASP.NET Core technology** - - For pre-release features, study code samples from linked PRs - - Consider version context - - Examine test cases to understand intended behavior - -3. **Special handling for labeled issues:** +1. Read the full issue and all linked references +2. Study code samples from linked PRs for pre-release features +3. For labeled issues: - **breaking-change:** Include breaking change guidance - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies - -## ASP.NET Core Specific Guidelines - -- Use the latest supported version for examples unless otherwise specified -- Lead with Microsoft recommended approaches -- Include differences between minimal API and controller-based approaches when relevant -- For middleware, lead with the middleware class approach -- For Blazor, clearly distinguish between Server and WebAssembly hosting models From d2f1046b25c2cc9bfeac22bef17d01702c1fd9de Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 25 Jul 2025 13:03:42 -0700 Subject: [PATCH 08/36] Update copilot-instructions.md Added build warning handling --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 859855d993a7..33f1eb8cce38 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -93,3 +93,4 @@ When creating a PR for an issue: - **breaking-change:** Include breaking change guidance - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies +4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. From 9cdbe3ba5f6c28452f9ae6fdef06131945664f4c Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 25 Jul 2025 13:24:42 -0700 Subject: [PATCH 09/36] Update copilot-instructions.md Added Markdown File Naming and Organization instruction, which is not found in the Style Guide, but important to call out. --- .github/copilot-instructions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 33f1eb8cce38..39960ca519fc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -53,6 +53,10 @@ This document contains repository-specific instructions for GitHub Copilot when - Get doc ID from the relevant XML doc in dotnet-api-docs - Omit first two characters of the doc ID +## 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. + ## Code Snippets - For snippets **longer than 6 lines**: From df5d6be561eeaa173c2426ef53ff48acba75d783 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 25 Jul 2025 13:42:03 -0700 Subject: [PATCH 10/36] Update copilot-instructions.md API ref guessing issue instruction. --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 39960ca519fc..1f5ca264617f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -34,7 +34,7 @@ This document contains repository-specific instructions for GitHub Copilot when ## API References and Verification -- Never guess API documentation IDs +- Never guess API documentation IDs, always verify. If unable to verfy, say so. - Check if features were introduced after .NET Core 3.1 - Default to most compatible syntax when uncertain - For breaking changes, check: From a2b1c1a44936f0298196970c83c60786bad68226 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 25 Jul 2025 15:32:41 -0700 Subject: [PATCH 11/36] Update .github/copilot-instructions.md add metadata ai-usage: ai-assisted --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1f5ca264617f..3252932fbb1b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -98,3 +98,4 @@ When creating a PR for an issue: - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. +5. If the meta data and value `ai-usage: ai-assisted` does not already exist in any .md files edited or created, then add it in. From f000dea7908af8628eb4de0ae188f455969dda7e Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 25 Jul 2025 15:33:43 -0700 Subject: [PATCH 12/36] Update .github/copilot-instructions.md --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3252932fbb1b..bbc8d6643f2b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -98,4 +98,4 @@ When creating a PR for an issue: - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. -5. If the meta data and value `ai-usage: ai-assisted` does not already exist in any .md files edited or created, then add it in. +5. If the metadata and value `ai-usage: ai-assisted` does not already exist in any .md files edited or created, then add it in. From e948babf59d8a3aa170c6ebe7d8e3bcbdb769ec1 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 25 Jul 2025 15:43:49 -0700 Subject: [PATCH 13/36] Update copilot-instructions.md Address breaking change feedback --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bbc8d6643f2b..c3a4c09514b1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -94,7 +94,7 @@ When creating a PR for an issue: 1. Read the full issue and all linked references 2. Study code samples from linked PRs for pre-release features 3. For labeled issues: - - **breaking-change:** Include breaking change guidance + - **breaking-change:** For general .NET breaking changes, reference [Breaking changes in .NET](../dotnet/core/compatibility/breaking-changes). For ASP.NET Core-specific breaking changes, add details to the "What's new" release notes file for the corresponding .NET version in this repo (using includes if appropriate), and cross-link to the main .NET breaking changes page. If no content is needed for a given release, ensure the release notes still link to the main breaking changes resource. - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. From 3157f4d237d03cdf0245ffa8dec6402056752ff3 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 28 Jul 2025 14:46:21 -0700 Subject: [PATCH 14/36] Ensure ms.date format and upate --- .github/copilot-instructions.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c3a4c09514b1..dd16d387ccb7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,7 +1,7 @@ --- author: wadepickett ms.author: wpickett -ms.date: 07-25-2025 +ms.date: 07-28-2025 --- # Copilot Instructions for `dotnet/AspNetCore.Docs` @@ -16,7 +16,10 @@ This document contains repository-specific instructions for GitHub Copilot when - **Repository Exceptions**: - Number ordered lists as "1." for every item (don't use sequential numbers) - Use `code style` specifically for file names, folders, custom types, and code that should never be localized - + - For any new .md file added to the repository or any updated .md file ensure the standaerd frontmatter (meta data) specified by the Style Guide is included. + - For any new .md file added to the repository or any updated .md file ensure the following frontmatter (meta data) is included. + - Metadata `ai-usage: ai-assisted` if any AI assistance was used + - Metadata `ms.date: ` with a format of DD-MM-YYYY in the frontmatter. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters have changed in the file. ## Version Targeting ### Detection Priority Order @@ -98,4 +101,4 @@ When creating a PR for an issue: - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. -5. If the metadata and value `ai-usage: ai-assisted` does not already exist in any .md files edited or created, then add it in. + From 270764d9d1d1b68465bd2326ef934f6446d3d06a Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 28 Jul 2025 14:48:13 -0700 Subject: [PATCH 15/36] Fixed typo --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index dd16d387ccb7..b366ea81ed4c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -19,7 +19,7 @@ This document contains repository-specific instructions for GitHub Copilot when - For any new .md file added to the repository or any updated .md file ensure the standaerd frontmatter (meta data) specified by the Style Guide is included. - For any new .md file added to the repository or any updated .md file ensure the following frontmatter (meta data) is included. - Metadata `ai-usage: ai-assisted` if any AI assistance was used - - Metadata `ms.date: ` with a format of DD-MM-YYYY in the frontmatter. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters have changed in the file. + - Metadata `ms.date: ` with a format of DD-MM-YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters have changed in the file. ## Version Targeting ### Detection Priority Order From 7ad64c91427224832a477c51e58f72503b2f2192 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Mon, 28 Jul 2025 14:49:35 -0700 Subject: [PATCH 16/36] Added blank line for formatting --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b366ea81ed4c..a63b0135338b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,6 +20,7 @@ This document contains repository-specific instructions for GitHub Copilot when - For any new .md file added to the repository or any updated .md file ensure the following frontmatter (meta data) is included. - Metadata `ai-usage: ai-assisted` if any AI assistance was used - Metadata `ms.date: ` with a format of DD-MM-YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters have changed in the file. + ## Version Targeting ### Detection Priority Order From 6d5fba26ae35f603c5e758541a667bd9b2f397c9 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 07:11:10 -0700 Subject: [PATCH 17/36] Update copilot-instructions.md Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a63b0135338b..d5ddedae4b77 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -38,7 +38,7 @@ This document contains repository-specific instructions for GitHub Copilot when ## API References and Verification -- Never guess API documentation IDs, always verify. If unable to verfy, say so. +- Never guess API documentation IDs, always verify. If unable to verfy, say so. - Check if features were introduced after .NET Core 3.1 - Default to most compatible syntax when uncertain - For breaking changes, check: From 873bf06ef086ac2e9c07b9443ce6ee7563f4f57d Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 07:12:20 -0700 Subject: [PATCH 18/36] Update copilot-instructions.md Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .github/copilot-instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d5ddedae4b77..11d2eb217f1b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -51,7 +51,8 @@ This document contains repository-specific instructions for GitHub Copilot when ## Links and References -- Use **relative links** for files within this repo +- Use relative links for files within this repo +- When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) - For learn.microsoft.com links, **remove** `https://learn.microsoft.com/en-us` from URLs - Use cross-references for APIs: `` - Get doc ID from the relevant XML doc in dotnet-api-docs From da4820754214c6c8874169439d1c8c9ff2db8fcc Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 07:12:51 -0700 Subject: [PATCH 19/36] Update copilot-instructions.md Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 11d2eb217f1b..9e9f1dd65785 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -53,7 +53,7 @@ This document contains repository-specific instructions for GitHub Copilot when - Use relative links for files within this repo - When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) -- For learn.microsoft.com links, **remove** `https://learn.microsoft.com/en-us` from URLs +- For learn.microsoft.com links, remove `https://learn.microsoft.com/en-us` from URLs - Use cross-references for APIs: `` - Get doc ID from the relevant XML doc in dotnet-api-docs - Omit first two characters of the doc ID From 6d195a1aa5bf300c7d551dbe2e8c1bf4dbd3d439 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 10:36:15 -0700 Subject: [PATCH 20/36] Apply suggestions from code review Adding some great suggested changes from guardrex. Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .github/copilot-instructions.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9e9f1dd65785..bf8d4afcb2b8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -15,11 +15,13 @@ This document contains repository-specific instructions for GitHub Copilot when - Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - **Repository Exceptions**: - Number ordered lists as "1." for every item (don't use sequential numbers) - - Use `code style` specifically for file names, folders, custom types, and code that should never be localized + - Use backticks, also called backquotes or graves, 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) - For any new .md file added to the repository or any updated .md file ensure the standaerd frontmatter (meta data) specified by the Style Guide is included. - For any new .md file added to the repository or any updated .md file ensure the following frontmatter (meta data) is included. - Metadata `ai-usage: ai-assisted` if any AI assistance was used - - Metadata `ms.date: ` with a format of DD-MM-YYYY. If the file already has a `ms.date` metadata, update it to today's date if more than 50 characters have changed in the file. + - The correct order of metadata lines is to place the title (`title`) first and the rest of the 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. ## Version Targeting @@ -83,14 +85,33 @@ This document contains repository-specific instructions for GitHub Copilot when ``` :::code language="csharp" source="~/path/to/file.cs" range="5-10" highlight="2-3"::: ``` -- Use modern C# coding patterns in all examples +- Use the latest, non-preview C# coding patterns in non-preview code examples +- Use the latest preview C# coding patterns in preview code examples + +The following table indicates the code language to use for markdown code blocks or the `language` attribute of a code snippet and the amount of indentation to use. + +Content of the snippet | Code language | Indentation in spaces +:---: | :---: | :---: +C# | csharp | 4 +HTML | html | 4 +CSS | css | 4 +JavaScript | javascript | 2 (4 spaces for line continuation) +XML | xml | 2 +JSON | json | 2 +Console | console | 2 +Text | - | 2 ## 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) +- 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, lead with the middleware class approach +- Include differences between Minimal API and controller-based approaches when relevant +- For middleware content and examples, use the middleware class approach - For Blazor, clearly distinguish between Server and WebAssembly hosting models ## Issue Handling From bbd4801cc860a4698e8c365c4daba4cec13daa4d Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 10:45:58 -0700 Subject: [PATCH 21/36] Update .github/copilot-instructions.md Corrected link for metadata specific guide --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bf8d4afcb2b8..04a7f65ab348 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -17,7 +17,7 @@ This document contains repository-specific instructions for GitHub Copilot when - Number ordered lists as "1." for every item (don't use sequential numbers) - Use backticks, also called backquotes or graves, 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) - - For any new .md file added to the repository or any updated .md file ensure the standaerd frontmatter (meta data) specified by the Style Guide is included. + - 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 .md file added to the repository or any updated .md file ensure the following frontmatter (meta data) is included. - Metadata `ai-usage: ai-assisted` if any AI assistance was used - The correct order of metadata lines is to place the title (`title`) first and the rest of the metadata lines in alphabetical order. Example: `title`, `author`, `description`, `monikerRange`, `ms.author`, `ms.custom`, `ms.date`, `uid`, `zone_pivot_groups` From 4d685d7e4b0edbe40ff07bda749c33e3dd29e658 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 10:55:36 -0700 Subject: [PATCH 22/36] Apply suggestions from code review Adding great suggestion from gewarren. Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .github/copilot-instructions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 04a7f65ab348..47c9ca7519d3 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -57,8 +57,7 @@ This document contains repository-specific instructions for GitHub Copilot when - When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) - For learn.microsoft.com links, remove `https://learn.microsoft.com/en-us` from URLs - Use cross-references for APIs: `` -- Get doc ID from the relevant XML doc in dotnet-api-docs -- Omit first two characters of the doc ID +- Get doc ID from the relevant XML doc in dotnet-api-docs, and omit the first two characters of the doc ID ## Markdown File Naming and Organization From 658b8ac727eeaf769f277be00a94822fb32a5091 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 10:59:12 -0700 Subject: [PATCH 23/36] Apply suggestions from code review Removed breaking change bullet as suggested by gewarren. --- .github/copilot-instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 47c9ca7519d3..f36ff5f0d320 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -119,7 +119,6 @@ When creating a PR for an issue: 1. Read the full issue and all linked references 2. Study code samples from linked PRs for pre-release features 3. For labeled issues: - - **breaking-change:** For general .NET breaking changes, reference [Breaking changes in .NET](../dotnet/core/compatibility/breaking-changes). For ASP.NET Core-specific breaking changes, add details to the "What's new" release notes file for the corresponding .NET version in this repo (using includes if appropriate), and cross-link to the main .NET breaking changes page. If no content is needed for a given release, ensure the release notes still link to the main breaking changes resource. - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. From 2f63cfad1f09aa0b108c05e33998cf2eaa5d838a Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 10:59:56 -0700 Subject: [PATCH 24/36] Update .github/copilot-instructions.md Removed vague Blazor specific instruction --- .github/copilot-instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f36ff5f0d320..e4d8b5788ab4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -111,7 +111,6 @@ Text | - | 2 - 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 -- For Blazor, clearly distinguish between Server and WebAssembly hosting models ## Issue Handling From 089f5b7eb6175d4ae410482718148e34731f3771 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Tue, 29 Jul 2025 11:15:29 -0700 Subject: [PATCH 25/36] Update .github/copilot-instructions.md --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e4d8b5788ab4..46d9d956d3c0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -18,7 +18,7 @@ This document contains repository-specific instructions for GitHub Copilot when - Use backticks, also called backquotes or graves, 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) - 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 .md file added to the repository or any updated .md file ensure the following frontmatter (meta data) is included. + - 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 - The correct order of metadata lines is to place the title (`title`) first and the rest of the 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. From 812fc7806c1a3d77618874fd99c68d23acc01946 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Tue, 29 Jul 2025 11:20:22 -0700 Subject: [PATCH 26/36] More suggestion added and clean up. --- .github/copilot-instructions.md | 24 +----------------------- 1 file changed, 1 insertion(+), 23 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 46d9d956d3c0..aaa0ca78f245 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,17 +1,15 @@ --- author: wadepickett ms.author: wpickett -ms.date: 07-28-2025 +ms.date: 07-29-2025 --- # Copilot Instructions for `dotnet/AspNetCore.Docs` ## Introduction - 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.** ## Repository-Specific Guidelines - - Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - **Repository Exceptions**: - Number ordered lists as "1." for every item (don't use sequential numbers) @@ -25,13 +23,6 @@ This document contains repository-specific instructions for GitHub Copilot when ## Version Targeting -### Detection Priority Order -1. **Explicit PR/Issue Instructions** - Prioritize explicit version ranges mentioned -2. **File Metadata** - Check YAML frontmatter for specifications -3. **Inline Moniker Tags** - Look for version range specifications -4. **Repository Branch Context** - Consider branch where PR will be merged -5. **Directory Structure** - Check for version-specific directories - ### Common Range Patterns - Fixed Range: `>= aspnetcore-7.0 <= aspnetcore-9.0` - Open Upper Bound: `>= aspnetcore-7.0` @@ -39,20 +30,11 @@ This document contains repository-specific instructions for GitHub Copilot when - Specific Version: `== aspnetcore-9.0` ## API References and Verification - - Never guess API documentation IDs, always verify. If unable to verfy, say so. - Check if features were introduced after .NET Core 3.1 - Default to most compatible syntax when uncertain -- For breaking changes, check: - - Changes to default behavior of existing APIs - - Removed or renamed public API elements - - Modified method signatures or return types - - Changed serialization formats - - Altered dependency requirements - - Changes to configuration schema ## Links and References - - Use relative links for files within this repo - When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) - For learn.microsoft.com links, remove `https://learn.microsoft.com/en-us` from URLs @@ -60,11 +42,9 @@ This document contains repository-specific instructions for GitHub Copilot when - Get doc ID from the relevant XML doc in dotnet-api-docs, and omit the first two characters of the doc ID ## 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. ## Code Snippets - - For snippets **longer than 6 lines**: - Place in separate `.cs` file in a `snippets` folder next to the Markdown file - Create a subfolder named after the document @@ -101,7 +81,6 @@ Console | console | 2 Text | - | 2 ## 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) - 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") @@ -113,7 +92,6 @@ Text | - | 2 - For middleware content and examples, use the middleware class approach ## Issue Handling - When creating a PR for an issue: 1. Read the full issue and all linked references 2. Study code samples from linked PRs for pre-release features From 74f1650b3b63881668dbbc81ef4076acbe3a0140 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Tue, 29 Jul 2025 12:04:09 -0700 Subject: [PATCH 27/36] Formatting and organziational fixes --- .github/copilot-instructions.md | 82 ++++++++++++++++----------------- 1 file changed, 40 insertions(+), 42 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index aaa0ca78f245..721a76b2371e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -9,6 +9,32 @@ ms.date: 07-29-2025 ## Introduction 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.** +## General Guidelines + +### Issue Handling +When creating a PR for an issue: +1. Read the full issue and all linked references +2. Study code samples from linked PRs for pre-release features +3. For labeled issues: + - **new-feature:** State which version introduced the feature + - **bug:** Focus on correcting technical inaccuracies +4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. + +### 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. + +### API References and Verification +- Never guess API documentation IDs, always verify. If unable to verfy, say so. +- Check if features were introduced after .NET Core 3.1 +- Default to most compatible syntax when uncertain + +### Links and References +- Use relative links for files within this repo +- When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) +- For learn.microsoft.com links, remove `https://learn.microsoft.com/en-us` from URLs +- Use cross-references for APIs: `` +- Get doc ID from the relevant XML doc in dotnet-api-docs, and omit the first two characters of the doc ID + ## Repository-Specific Guidelines - Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - **Repository Exceptions**: @@ -21,30 +47,13 @@ This document contains repository-specific instructions for GitHub Copilot when - The correct order of metadata lines is to place the title (`title`) first and the rest of the 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. -## Version Targeting - -### Common Range Patterns +### 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` -## API References and Verification -- Never guess API documentation IDs, always verify. If unable to verfy, say so. -- Check if features were introduced after .NET Core 3.1 -- Default to most compatible syntax when uncertain - -## Links and References -- Use relative links for files within this repo -- When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) -- For learn.microsoft.com links, remove `https://learn.microsoft.com/en-us` from URLs -- Use cross-references for APIs: `` -- Get doc ID from the relevant XML doc in dotnet-api-docs, and omit the first two characters of the doc ID - -## 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. - -## Code Snippets +### Code Snippets - For snippets **longer than 6 lines**: - Place in separate `.cs` file in a `snippets` folder next to the Markdown file - Create a subfolder named after the document @@ -66,21 +75,20 @@ This document contains repository-specific instructions for GitHub Copilot when ``` - 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 code language and indentation standards for markdown code blocks or the `language` attribute of code snippets: -The following table indicates the code language to use for markdown code blocks or the `language` attribute of a code snippet and the amount of indentation to use. + Content of the snippet | Code language | Indentation in spaces + :---: | :---: | :---: + C# | csharp | 4 + HTML | html | 4 + CSS | css | 4 + JavaScript | javascript | 2 (4 spaces for line continuation) + XML | xml | 2 + JSON | json | 2 + Console | console | 2 + Text | - | 2 -Content of the snippet | Code language | Indentation in spaces -:---: | :---: | :---: -C# | csharp | 4 -HTML | html | 4 -CSS | css | 4 -JavaScript | javascript | 2 (4 spaces for line continuation) -XML | xml | 2 -JSON | json | 2 -Console | console | 2 -Text | - | 2 - -## ASP.NET Core Specific Guidelines +### 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) - 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") @@ -90,13 +98,3 @@ Text | - | 2 - 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 - -## Issue Handling -When creating a PR for an issue: -1. Read the full issue and all linked references -2. Study code samples from linked PRs for pre-release features -3. For labeled issues: - - **new-feature:** State which version introduced the feature - - **bug:** Focus on correcting technical inaccuracies -4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. - From 06fa80ac84134d126049a31de59209ee8281937b Mon Sep 17 00:00:00 2001 From: wadepickett Date: Tue, 29 Jul 2025 12:24:10 -0700 Subject: [PATCH 28/36] Added guardrex code snippet suggestions --- .github/copilot-instructions.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 721a76b2371e..ff09222a384d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,7 +7,7 @@ ms.date: 07-29-2025 # Copilot Instructions for `dotnet/AspNetCore.Docs` ## Introduction -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.** +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.** ## General Guidelines @@ -54,12 +54,15 @@ When creating a PR for an issue: - Specific Version: `== aspnetcore-9.0` ### Code Snippets -- For snippets **longer than 6 lines**: - - Place in separate `.cs` file in a `snippets` folder next to the Markdown file - - Create a subfolder named after the document - - For version-specific code, include a version folder - - Add a simple `.csproj` file targeting the appropriate .NET version - +- For code snippets longer than 6 lines: + 1. Create a subfolder named after the document the snippet supports. + 1. Create a `snippets` folder inside that subfolder. + 1. 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: + 1. Create a subfolder inside the `snippets` folder named for the version (for example, `9.0` for .NET 9 or ASP.NET Core 9). + 1. Place the code in a file with the correct extension inside the version subfolder. + 1. 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 specific to a single doc file: ``` From d9d187b56a60ae06711744c5221b8657052f893a Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Wed, 30 Jul 2025 10:40:46 -0700 Subject: [PATCH 29/36] Update .github/copilot-instructions.md --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ff09222a384d..6f3c37eff5dd 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -24,7 +24,7 @@ When creating a PR for an issue: - 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. ### API References and Verification -- Never guess API documentation IDs, always verify. If unable to verfy, say so. +- Never guess API documentation IDs, always verify. If unable to verify, say so. - Check if features were introduced after .NET Core 3.1 - Default to most compatible syntax when uncertain From d378c114f61df30f66d1d1b2992ccb6344229ecf Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Wed, 30 Jul 2025 17:38:33 -0700 Subject: [PATCH 30/36] Update .github/copilot-instructions.md Co-authored-by: Tom Dykstra --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6f3c37eff5dd..db2b1401140c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -39,7 +39,7 @@ When creating a PR for an issue: - Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - **Repository Exceptions**: - Number ordered lists as "1." for every item (don't use sequential numbers) - - Use backticks, also called backquotes or graves, 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 + - 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) - 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: From e16c8577466f100d8c6afb8330bc565804646d37 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Wed, 30 Jul 2025 18:13:27 -0700 Subject: [PATCH 31/36] Apply suggestions from code review Co-authored-by: Tom Dykstra --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index db2b1401140c..57555c151f9c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -64,7 +64,7 @@ When creating a PR for an issue: 1. Place the code in a file with the correct extension inside the version subfolder. 1. 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 specific to a single doc file: + - **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"::: ``` From 2ac229cde7d864afa1665a2aa46444c82266510e Mon Sep 17 00:00:00 2001 From: wadepickett Date: Wed, 30 Jul 2025 22:03:33 -0700 Subject: [PATCH 32/36] Updates per tdykstra suggestions --- .github/copilot-instructions.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 57555c151f9c..cdf567993884 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -25,15 +25,21 @@ When creating a PR for an issue: ### API References and Verification - Never guess API documentation IDs, always verify. If unable to verify, say so. -- Check if features were introduced after .NET Core 3.1 -- Default to most compatible syntax when uncertain +- Use `` for API cross-references. The documentation ID must be verified and sourced from the official XML documentation in dotnet-api-docs. ### Links and References -- Use relative links for files within this repo -- When adding external links into a document, strip out the language/culture segment of the URL if present (example: remove the `en-us` or `en` part of links to English versions of webpages) -- For learn.microsoft.com links, remove `https://learn.microsoft.com/en-us` from URLs -- Use cross-references for APIs: `` -- Get doc ID from the relevant XML doc in dotnet-api-docs, and omit the first two characters of the doc ID +- 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. +- For external links, always remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.). + - Example (Microsoft Learn): + - Original: `https://learn.microsoft.com/en-us/aspnet/core/blazor/` + - Correct: `https://learn.microsoft.com/aspnet/core/blazor/` + - Example (Wikipedia): + - Original: `https://en.wikipedia.org/wiki/ASP.NET_Core` + - Correct: `https://wikipedia.org/wiki/ASP.NET_Core` +- For Microsoft Learn links, also strip the base domain (`https://learn.microsoft.com/en-us`) so only the path remains. + - Example: + - Original: `https://learn.microsoft.com/en-us/aspnet/core/blazor/` + - Correct: `/aspnet/core/blazor/` ## Repository-Specific Guidelines - Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) @@ -78,9 +84,9 @@ When creating a PR for an issue: ``` - 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 code language and indentation standards for markdown code blocks or the `language` attribute of code snippets: +- Use the following language code and indentation standards for markdown code blocks or the `language` attribute of code snippets: - Content of the snippet | Code language | Indentation in spaces + Content of the snippet | Language code | Indentation in spaces :---: | :---: | :---: C# | csharp | 4 HTML | html | 4 From ca17b39cdb350d7981b9188810ec5dd1af1af9cb Mon Sep 17 00:00:00 2001 From: wadepickett Date: Thu, 31 Jul 2025 10:00:59 -0700 Subject: [PATCH 33/36] Fixed pre-view instruction per tdykstra suggestion --- .github/copilot-instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index cdf567993884..7825252119fa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -14,8 +14,8 @@ This document contains general and repository-specific instructions for GitHub C ### Issue Handling When creating a PR for an issue: 1. Read the full issue and all linked references -2. Study code samples from linked PRs for pre-release features -3. For labeled issues: +2. Study code samples from linked PRs that demonstrate features in the latest .NET pre-release version (e.g., .NET 10 Preview) to ensure guidance and documentation reflect the latest upcoming changes and best practices. +3. 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 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. From 999a2746c81d9daf2ace00077e86da9f6ba1b0ff Mon Sep 17 00:00:00 2001 From: wadepickett Date: Thu, 31 Jul 2025 10:23:19 -0700 Subject: [PATCH 34/36] update for API ref verify per tdykstra suggestion --- .github/copilot-instructions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7825252119fa..47f93acf32d7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,7 +1,7 @@ --- author: wadepickett ms.author: wpickett -ms.date: 07-29-2025 +ms.date: 07-31-2025 --- # Copilot Instructions for `dotnet/AspNetCore.Docs` @@ -24,8 +24,9 @@ When creating a PR for an issue: - 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. ### API References and Verification -- Never guess API documentation IDs, always verify. If unable to verify, say so. -- Use `` for API cross-references. The documentation ID must be verified and sourced from the official XML documentation in dotnet-api-docs. + - 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. ### Links and References - 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. From f9a8aa68b089cf462f1a45e37afe4efc23e4eddc Mon Sep 17 00:00:00 2001 From: wadepickett Date: Thu, 31 Jul 2025 10:28:12 -0700 Subject: [PATCH 35/36] Added issue overview instructions per tdykstra suggestion --- .github/copilot-instructions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 47f93acf32d7..f48d165ff89e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -19,6 +19,8 @@ When creating a PR for an issue: - **new-feature:** State which version introduced the feature - **bug:** Focus on correcting technical inaccuracies 4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. +5. Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information. +6. Include the folder structure of the repository, including any important directories or files that are relevant to the project. ### 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. From 171777fa2daa5fa92f86ab3e3f954de942b76c40 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Thu, 31 Jul 2025 10:36:19 -0700 Subject: [PATCH 36/36] One last check for grammar --- .github/copilot-instructions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f48d165ff89e..771ff1c44ddc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -14,11 +14,11 @@ This document contains general and repository-specific instructions for GitHub C ### Issue Handling When creating a PR for an issue: 1. Read the full issue and all linked references -2. Study code samples from linked PRs that demonstrate features in the latest .NET pre-release version (e.g., .NET 10 Preview) to ensure guidance and documentation reflect the latest upcoming changes and best practices. +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. 3. 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 -4. When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure 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. +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. 5. Provide an overview of the project you're working on, including its purpose, goals, and any relevant background information. 6. Include the folder structure of the repository, including any important directories or files that are relevant to the project. @@ -53,7 +53,7 @@ When creating a PR for an issue: - 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 - - The correct order of metadata lines is to place the title (`title`) first and the rest of the metadata lines in alphabetical order. Example: `title`, `author`, `description`, `monikerRange`, `ms.author`, `ms.custom`, `ms.date`, `uid`, `zone_pivot_groups` + - 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. ### Version Targeting Common Range Patterns @@ -94,7 +94,7 @@ When creating a PR for an issue: C# | csharp | 4 HTML | html | 4 CSS | css | 4 - JavaScript | javascript | 2 (4 spaces for line continuation) + JavaScript | javascript | 2 spaces (use 4 spaces for line continuation) XML | xml | 2 JSON | json | 2 Console | console | 2 @@ -107,6 +107,6 @@ When creating a PR for an issue: - 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 +- 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