Merge main into live

.github/copilot-instructions.md

@@ -2,48 +2,34 @@
 
 ## Disclosure
 
-IMPORTANT: 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:
+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:
 
-```markdown
-ai-usage: ai-generated
-```
-
-## Terminology
+- When reviewing a PR not created by AI:
 
-- Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
+  ```markdown
+  ai-usage: ai-assisted
+  ```
 
-## Writing Style
+- When Copilot generates the article through GitHub without the use of a human:
 
-Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics:
+  ```markdown
+  ai-usage: ai-generated
+  ```
 
-### Voice and Tone
+- When using an IDE with a human guiding AI:
 
-- 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.
+  ```markdown
+  ai-usage: ai-assisted
+  ```
 
-### Structure and Format
+## New articles
 
-- Sentence case headings (no gerunds in titles).
-- Be concise, break up long sentences.
-- IMPORTANT: Oxford comma in lists.
-- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.)
-- IMPORTANT: Use bullets for unordered lists.
-- VERY IMPORTANT: 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".
-- No consecutive headings without content between them.
+- New articles must follow a template in the /.github/projects/article-templates/ folder.
+- If you don't know which template to use, ask.
 
-### 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
 
@@ -66,11 +52,66 @@ For snippets >6 lines:
 1. Create examples in both C# and Visual Basic unless the article referencing the snippet resides in the in the `csharp`, `fsharp`, and `visual-basic` language folders.
 1. When you add code, use code comments sparingly because they don't get localized. You can use them to briefly clarify code-specific details (such as logic, parameters, or edge cases). Put any critical information and context in the markdown text of the referencing article.
 
+## .NET Framework vs .NET differences
+
+When documenting differences between .NET Framework and .NET (like .NET 6 and newer), choose the appropriate system:
+
+### Use Tabs
+Use tabbed content when the differences are code-based:
+
+```markdown
+# [.NET](#tab/dotnet)
+
+<how it works in .NET>
+
+# [.NET Framework](#tab/dotnetframework)
+
+<how it works in .NET Framework>
+
+---
+```
+
+### Use Pivots
+Use zone pivots when there are conceptual differences that can't easily be explained with tabs and a note. Pivots allow for more comprehensive explanations of different approaches or methodologies.
+
+To use zone pivots:
+
+1. Add `zone_pivot_groups: desktop-version` to the article's frontmatter
+2. Use zone pivot syntax in content:
+
+```markdown
+::: zone pivot="dotnet"
+
+Your .NET content here
+
+::: zone-end
+
+::: zone pivot="dotnetframework"
+
+Your .NET Framework content here
+
+::: zone-end
+```
+
 ## File Naming
 
 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.
+### GitHub Issue Assignment (AI Workflow)
+When assigned an issue 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: 'dotnet-desktop-guide/**/*.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/projects/article-templates/doc-guide.yml

@@ -0,0 +1,14 @@
+# ms.topic: <implementation-name> version 1.0.0
+items:
+- name: <Suggested title>
+  href: <path-template>
+  required: yes
+  limit: 1
+- name: <Suggested title>
+  href: <path-template>
+  required: yes
+  limit: 1
+- name: <Suggested title>
+  href: <path-template>
+  required: No
+  limit: none

.github/projects/article-templates/doc-toc.yml

@@ -0,0 +1,14 @@
+# ms.topic: <implementation-name> version 1.0.0
+items:
+- name: <Suggested title>
+  href: /<guide-name>/toc.yml
+  required: yes
+  limit: 1
+- name: <Suggested title>
+  href: /<guide-name>/toc.yml
+  required: yes
+  limit: 1
+- name: <Suggested title>
+  href: /<guide-name>/toc.yml
+  required: yes
+  limit: none

.github/projects/article-templates/general-troubleshoot.md

@@ -0,0 +1,143 @@
+---
+title: [Follow SEO guidance at 
+https://review.learn.microsoft.com/en-us/help/platform/seo-meta-title]
+description: "[Article description]."
+author: [your GitHub alias]
+ms.author: [your Microsoft alias or a team alias]
+ms.service: [the approved service name]
+ms.topic: troubleshooting-general #Don't change.
+ms.date: [mm/dd/yyyy]
+
+#customer intent: As a <role>, I want <what> so that <why>.
+
+---
+
+<!-- --------------------------------------
+
+- Use this template with pattern instructions for:
+
+Troubleshooting
+
+- Before you sign off or merge:
+
+Remove all comments except the customer intent.
+
+- Feedback:
+
+https://aka.ms/patterns-feedback
+
+-->
+
+# Troubleshoot [issues with a product or service]
+
+<!-- Required: Article headline - H1
+
+Identify the product or service the article
+applies to.
+
+-->
+
+[Introduce and explain the purpose of the article.]
+
+<!-- Required: Introductory paragraphs (no heading)
+
+Write a brief introduction that can help the user
+determine whether the article is relevant for them
+and to describe the specific issue that the article
+covers.
+
+-->
+
+## Prerequisites
+
+<!-- Optional: Prerequisites - H2
+
+If this section is needed, make "Prerequisites" the
+first H2 in the article.
+
+Use clear and unambiguous language, and use
+an unordered list format. 
+
+-->
+
+## [Potential quick workarounds]
+
+1. Procedure step
+1. Procedure step
+
+<!-- Optional: Potential quick workarounds - H2
+
+An issue might be able to be temporarily resolved with a
+quick fix. If one is known, list any workarounds that can be
+implemented quickly to resolve the issue. Link to
+information about longer-term solutions in the
+"Solution" section.
+
+-->
+
+## [Troubleshooting checklist]
+
+### [Troubleshooting step]
+
+<!-- Required: Troubleshooting checklist - H2
+
+Provide guidance about how the user can troubleshoot
+the issues and determine the cause of the issue. You
+can include H3 sections to describe the troubleshooting
+steps. 
+
+-->
+
+## [Causes and/or solutions]
+
+### [Solution] 
+
+1. Procedure step
+1. Procedure step
+
+<!-- Required: Causes and/or solutions - H2
+
+Provide at least one cause or solution. Define the 
+cause of the issue if it's known.
+
+If the problem is correctable, include one or more
+solutions. Use H3 sections for troubleshooting steps.
+
+Make sure that the H3 solution headings clearly state the 
+intention ofthe solution section. Each solution section 
+should have a short sentence that describes the steps 
+that are about to be taken.
+
+-->
+
+## [Advanced troubleshooting and data collection]
+
+<!-- Optional: Advanced troubleshooting/data collection - H2
+
+Include this section if advanced troubleshooting is
+needed and might require a call for support. List any
+information or procedures in this section to help the user
+submit a support ticket. You can use numbered steps or 
+blocks of text. 
+
+-->
+
+## Related content
+
+- [Related article title](link.md)
+- [Related article title](link.md)
+- [Related article title](link.md)
+
+<!-- Optional: Related content - H2
+
+Consider including a "Related content" H2 section that 
+lists links to 1 to 3 articles the user might find helpful.
+
+-->
+
+<!--
+
+Remove all comments except the customer intent
+before you sign off or merge to the main branch.
+
+-->