Merge pull request #49067 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

.github/copilot-instructions.md

@@ -1,51 +1,28 @@
 # .NET Documentation Guidelines
 
-## Disclosure
+IMPORTANT: For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. If missing, add the `ai-usage` frontmatter key/value pair:
 
-For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair:
+- When reviewing a PR not created by AI:
 
-```markdown
-ai-usage: ai-generated
-```
+  ```markdown
+  ai-usage: ai-assisted
+  ```
 
-## Terminology
-
-Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
-
-## Writing Style
-
-Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics:
+- When Copilot generates the article through GitHub without the use of a human:
 
-### Voice and Tone
+  ```markdown
+  ai-usage: ai-generated
+  ```
 
-- Active voice, second person addressing reader directly.
-- Conversational tone with contractions.
-- Present tense for instructions/descriptions.
-- Imperative mood for instructions ("Call the method" not "You should call the method").
-- Use "might" instead of "may" for possibility.
-- Use "can" instead of "may" for permissible actions.
-- Avoid "we"/"our" referring to documentation authors or product teams.
+- When using an IDE with a human guiding AI:
 
-### Structure and Format
+  ```markdown
+  ai-usage: ai-assisted
+  ```
 
-- Sentence case headings (no gerunds in titles).
-- Be concise, break up long sentences.
-- Oxford comma in lists.
-- Use bullets for unordered lists.
-- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.)
-- Ordered and unordered lists should use complete sentences with proper punctuation, ending with a period if it's more than three words.
-- Avoid "etc." or "and so on" - provide complete lists or use "for example".
-- Use "for example" instead of "e.g.".
-- Use "that is" instead of "i.e.".
-- No consecutive headings without content between them.
-
-### Formatting Conventions
+## Terminology
 
-- **Bold** for UI elements.
-- `Code style` for file names, folders, custom types, non-localizable text.
-- Raw URLs in angle brackets.
-- Use relative links for files in this repo.
-- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links.
+Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
 
 ## API References
 
@@ -72,7 +49,24 @@ For snippets >6 lines:
 
 New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.).
 
+Examples:
+- ✅ Good: `getting-started-with-entity-framework.md`
+- ✅ Good: `configure-logging.md`
+- ✅ Good: `dependency-injection-guidelines.md`
+- ❌ Bad: `Getting-Started-With-The-Entity-Framework.md`
+- ❌ Bad: `configure_logging.md`
+- ❌ Bad: `DependencyInjectionGuidelines.md`
+
 ## Special Cases
 
-- Breaking changes: Include directions from `.github/prompts/breaking-change.md`.
-- When you (Copilot) are assigned an issue in GitHub, 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.
+### Breaking Changes
+- Include directions from `.github/prompts/breaking-change.md`.
+
+### GitHub Issue Assignment (AI Workflow)
+When assigned an issue or directly given a task in GitHub:
+1. Complete your work
+2. Wait for workflows (status checks) to run
+3. Check for build warnings in the OpenPublishing.Build status check
+4. If warnings exist:
+   - Click "View Details" to open the build report
+   - Resolve any build warnings you introduced

.github/instructions/Markdown.WritingStyle.instructions.md

@@ -0,0 +1,83 @@
+---
+applyTo: docs/**/*.md,includes/**/*.md
+description: 'Follow these comprehensive writing style guidelines when creating or editing Markdown documentation. Apply active voice, conversational tone, Oxford commas, and specific formatting rules to ensure consistency and readability across all documentation.'
+---
+
+# Markdown Writing Style Instructions
+
+When writing or editing Markdown documentation, follow these style guidelines:
+
+## Voice and Tone Requirements
+
+ALWAYS write using:
+- Active voice with second person ("you")
+- Conversational tone with contractions
+- Present tense for instructions and descriptions
+- Imperative mood for instructions (write "Call the method" NOT "You should call the method")
+- "might" for possibility (NOT "may")
+- "can" for permissible actions (NOT "may")
+
+NEVER use:
+- "we" or "our" when referring to documentation authors or product teams
+- Jargon or overly complex technical language
+- Weak phrases like "you can" or "there is/are/were" unless they add value
+
+ALWAYS:
+- Write like you speak using everyday words
+- Create a friendly, informal tone
+- Start statements with verbs when possible
+
+## Structure and Format Rules
+
+### Headings and Content
+- Use sentence case headings (capitalize only first word and proper nouns)
+- Never use gerunds in titles
+- Never place consecutive headings without content between them
+- Lead with the most important information first
+- Front-load keywords for scanning
+
+### Lists and Punctuation
+- **CRITICAL: Use Oxford comma in ALL lists (item1, item2, and item3) - NO EXCEPTIONS**
+- **MANDATORY: Number ordered lists using "1." for every item (NOT 1., 2., 3.) - ALWAYS USE "1."**
+- **REQUIRED: Use bullets for unordered lists - NEVER use numbers for unordered content**
+- **ESSENTIAL: Write complete sentences in lists with proper punctuation**
+- **MUST: End list items with periods if more than three words - THIS IS NON-NEGOTIABLE**
+- Skip end punctuation on titles, headings, and UI elements (3 words or fewer)
+
+### Spacing and Layout
+- Add blank lines around Markdown elements (but don't add extra if they exist)
+- Use only one space after periods, question marks, and colons
+- Use no spaces around dashes (word—word)
+- Break up long sentences for clarity
+
+### Prohibited Terms
+- Never write "etc." or "and so on" - provide complete lists or use "for example"
+- Use "for example" instead of "e.g."
+- Use "that is" instead of "i.e."
+
+## Formatting Conventions
+
+Apply these formatting rules:
+- **Bold text** for UI elements
+- `Code style` for file names, folders, custom types, and non-localizable text
+- Raw URLs in angle brackets
+- Relative links for files in this repository
+- Remove `https://learn.microsoft.com/en-us` from Microsoft Learn links
+
+## Word Choice Requirements
+
+### Verb Selection
+- Choose simple verbs without modifiers
+- Avoid weak verbs: "be," "have," "make," "do"
+- Use precise verbs (write "tell" NOT "inform")
+
+### Conciseness Rules
+- Use one word instead of multiple when possible (write "to" NOT "in order to")
+- Choose words with one clear meaning (write "because" NOT "since" for causation)
+- Omit unnecessary adverbs unless critical to meaning
+- Use one term consistently for each concept
+
+### Contraction Guidelines
+- Use common contractions: "it's," "you're," "that's," "don't"
+- Avoid ambiguous contractions: "there'd," "it'll," "they'd"
+- Never form contractions from noun + verb (avoid "Microsoft's developing")

.github/instructions/Snippets.Migrate.instructions.md

@@ -0,0 +1,121 @@
+---
+description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location.
+---
+
+# Migrate code snippets
+
+**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles referencing the same snippets.
+
+## Repository structure for code snippets
+
+**IMPORTANT**: This repository has TWO different locations for code snippets:
+
+### Old location (legacy - to be migrated FROM)
+- Path: `~/samples/snippets/`
+- Example: `~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.Clipboard/CS/form1.cs`
+- Status: Legacy, should be migrated to new location
+
+### New location (current standard - migrate TO)
+- Path pattern: `./snippets/{doc-file}/{code-language}/`
+- Example: `./snippets/how-to-add-data-to-the-clipboard/csharp/form1.cs`
+
+**Path components explained:**
+- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension
+  - Example: For article `how-to-add-data-to-the-clipboard.md` → use `how-to-add-data-to-the-clipboard`
+- `{code-language}`: 
+  - `csharp`: For C# code
+  - `vb`: For Visual Basic code
+
+## Legacy code characteristics (migrate FROM these)
+
+**Location**: `~/samples/snippets/` folder
+**Problems with legacy code:**
+- Usually for .NET Framework (outdated)
+- Often incomplete or non-compilable
+- May lack project files
+- Uses outdated syntax and patterns
+
+**Legacy article references look like this:**
+```markdown
+[!code-{code-language}[description](~/samples/snippets/{path-to-file}#{snippet-identifier})]
+```
+It's possible that the reference was already migrated, but the code wasn't, which looks like this:
+```markdown
+:::code language="{code-language}" source="~/samples/snippets/{path-to-file}" id="{snippet-identifier}":::
+```
+Based on the {path-to-file} you can determine if it's in the old system or not.
+
+## Current code requirements (migrate TO these)
+
+**Location**: `./snippets/{doc-file}/{code-language}/`
+
+**Requirements for current code standards:**
+- ✅ MUST be complete and compilable
+- ✅ MUST include a project file
+- ✅ MUST target appropriate .NET version (see targeting rules below)
+- ✅ MUST provide BOTH C# and Visual Basic versions
+- ✅ MUST use appropriate syntax for the target framework
+- ✅ MUST use meaningful, descriptive snippet identifiers in CamelCase format
+  - **Examples** of good snippet identifiers: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling`
+  - **Avoid** simplistic identifiers like `1`, `2`, `code1`, or `snippet1`
+
+**Current article references look like this:**
+```markdown
+:::code language="{code-language}" source="{file-path}" id="{snippet-identifier}":::
+```
+
+**Framework targeting rules:**
+- **Migration vs. Modernization**: 
+  - **Migration**: Move code to new location with minimal changes
+  - **Modernization**: Update code to use latest .NET features and best practices
+- **When to modernize**: Unless told not to modernize, always modernize from .NET Framework to the latest .NET
+
+## Migration steps (follow in order)
+
+**WHEN TO MIGRATE**: Migrate code when you encounter articles with references to `~/samples/snippets/` paths.
+
+**STEP-BY-STEP PROCESS:**
+
+### 1. Analyze existing code and article context
+- **Find**: Locate the legacy snippet file in `~/samples/snippets/`
+- **Identify**: Determine the programming language (C# or Visual Basic)
+- **Extract**: Note the snippet identifier used in the article reference
+
+### 2. Create new folder structure
+- **Pattern**: `./snippets/{doc-file}/{code-language}/`
+- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/csharp/`
+
+### 3. Migrate and update code
+- **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location
+- **Complete**: Ensure code is fully functional and compilable
+- **Project file**: Create or update project file with appropriate target framework
+
+### 4. Create both language versions
+- **Requirement**: MUST provide both C# and Visual Basic versions
+- **C# path**: `./snippets/{doc-file}/csharp/`
+- **VB path**: `./snippets/{doc-file}/vb/`
+
+### 5. Update article references
+- **Replace**: Change from legacy `[!code-...]` format to modern `:::code...:::` format
+- **Before**: `[!code-csharp[description](~/samples/snippets/path/file.cs#snippet1)]`
+- **After**: `:::code language="csharp" source="./snippets/doc-name/csharp/file.cs" id="BasicClipboardData":::`
+- **Note**: Use meaningful CamelCase identifiers instead of simple numbers
+
+### 6. Validate
+- **Build**: Ensure all code compiles successfully
+- **Test**: Verify snippet references work in the article
+
+### 7. Delete
+- **Identify**:
+  - Check if the old snippet file is used by any other articles
+  - Some articles may use a relative path to the `samples` folder, so simply search for links to `samples/snippets/...`
+  - Be confident that all legacy snippets use a `samples/snippets` folder structure
+- **Delete**: If old snippet is no longer used by any article, delete it.
+
+## Common mistakes to avoid
+
+- ❌ **Don't** assume all code needs to be modernized - check article context first
+- ❌ **Don't** modernize .NET Framework-specific articles unless specifically requested
+- ❌ **Don't** forget to create both C# and VB versions
+- ❌ **Don't** forget to update ALL article references to the migrated code
+- ❌ **Don't** leave incomplete or non-compilable code