From ed4274af1e793f83142d809bea90c261e80d7872 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 13 Mar 2026 12:07:50 -0700 Subject: [PATCH 1/8] Convert instructions to prompts --- .../Snippets.Migrate.prompt.md} | 53 ++++++--- .../Snippets.Push.prompt.md} | 58 ++++++--- .github/prompts/Snippets.Upgrade.prompt.md | 111 ++++++++++++++++++ 3 files changed, 193 insertions(+), 29 deletions(-) rename .github/{instructions/Snippets.Migrate.instructions.md => prompts/Snippets.Migrate.prompt.md} (61%) rename .github/{instructions/Snippets.Push.instructions.md => prompts/Snippets.Push.prompt.md} (54%) create mode 100644 .github/prompts/Snippets.Upgrade.prompt.md diff --git a/.github/instructions/Snippets.Migrate.instructions.md b/.github/prompts/Snippets.Migrate.prompt.md similarity index 61% rename from .github/instructions/Snippets.Migrate.instructions.md rename to .github/prompts/Snippets.Migrate.prompt.md index a5efb8732895b..1632efccfc391 100644 --- a/.github/instructions/Snippets.Migrate.instructions.md +++ b/.github/prompts/Snippets.Migrate.prompt.md @@ -1,4 +1,6 @@ --- +agent: agent +model: Claude Sonnet 4 (copilot) description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location. --- @@ -16,12 +18,16 @@ description: Migrate code from the old ~/samples/snippets/ location to the relat - 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 pattern: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` +- Example: `./snippets/how-to-add-data-to-the-clipboard/net/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` +- `[net-or-framework]`: Choose based on target framework: + - `net`: For .NET (.NET 6 and newer) + - `framework`: For .NET Framework (4.8 and older) + - **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches - `{code-language}`: - `csharp`: For C# code - `vb`: For Visual Basic code @@ -30,7 +36,7 @@ description: Migrate code from the old ~/samples/snippets/ location to the relat **Location**: `~/samples/snippets/` folder **Problems with legacy code:** -- Usually for .NET Framework (outdated) +- Written for .NET Framework (outdated) - Often incomplete or non-compilable - May lack project files - Uses outdated syntax and patterns @@ -39,15 +45,10 @@ description: Migrate code from the old ~/samples/snippets/ location to the relat ```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}/` +**Location**: `./snippets/{doc-file}/[framework]/{code-language}/` **Requirements for current code standards:** - ✅ MUST be complete and compilable @@ -68,7 +69,12 @@ Based on the {path-to-file} you can determine if it's in the old system or not. - **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 +- **When to migrate only**: When article has `ms.service: dotnet-framework` frontmatter or is specifically about .NET Framework features +- **When to modernize**: When article demonstrates both .NET and .NET Framework, or when specifically requested +- **Default targeting**: + - For .NET Framework-specific articles: Keep targeting .NET Framework + - For general articles: Target latest .NET version (e.g., .NET 10) + - For mixed articles: Create separate snippets in `net/` and `framework/` subfolders ## Migration steps (follow in order) @@ -78,32 +84,47 @@ Based on the {path-to-file} you can determine if it's in the old system or not. ### 1. Analyze existing code and article context - **Find**: Locate the legacy snippet file in `~/samples/snippets/` +- **Check frontmatter**: Look for `ms.service: dotnet-framework` in the article's frontmatter +- **Determine scope**: + - If frontmatter has `ms.service: dotnet-framework` → this is likely a .NET Framework-specific article + - if frontmatter has `ms.service: dotnet-desktop` or similar → this is likely a dual-framework or general article + - If article demonstrates both .NET and .NET Framework → prepare for dual targeting + - If article is general purpose → consider targeting current .NET - **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/` +- **Pattern**: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` +- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/net/csharp/` +- **Decision tree for framework folder**: + - Article has `ms.service: dotnet-framework` frontmatter → use `./snippets/{doc-file}/framework/{code-language}/` + - Article shows ONLY current .NET examples → use `./snippets/{doc-file}/{code-language}/` (omit framework folder) + - Article shows BOTH .NET and .NET Framework → create both `./snippets/{doc-file}/net/{code-language}/` and `./snippets/{doc-file}/framework/{code-language}/` ### 3. Migrate and update code - **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location +- **Update approach**: + - **For .NET Framework articles**: Migrate with minimal changes, keep .NET Framework targeting + - **For dual-framework articles**: Create both versions with appropriate targeting and update frontmatter to `ms.service: dotnet-desktop` + - **For general articles**: Update to target current .NET only if specifically requested or if article demonstrates modernization - **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/` +- **C# path**: `./snippets/{doc-file}/[framework]/csharp/` +- **VB path**: `./snippets/{doc-file}/[framework]/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":::` +- **After**: `:::code language="csharp" source="./snippets/doc-name/net/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 +- **Clean**: Remove unused legacy files (if no other articles reference them) ### 7. Delete - **Identify**: @@ -116,6 +137,8 @@ Based on the {path-to-file} you can determine if it's in the old system or not. - ❌ **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** ignore the `ms.service: dotnet-framework` frontmatter indicator - ❌ **Don't** forget to create both C# and VB versions +- ❌ **Don't** mix up the framework targeting (net vs framework) - ❌ **Don't** forget to update ALL article references to the migrated code - ❌ **Don't** leave incomplete or non-compilable code diff --git a/.github/instructions/Snippets.Push.instructions.md b/.github/prompts/Snippets.Push.prompt.md similarity index 54% rename from .github/instructions/Snippets.Push.instructions.md rename to .github/prompts/Snippets.Push.prompt.md index c9fef42c545a0..d3ef3398086cf 100644 --- a/.github/instructions/Snippets.Push.instructions.md +++ b/.github/prompts/Snippets.Push.prompt.md @@ -1,4 +1,6 @@ --- +agent: agent +model: Claude Sonnet 4 (copilot) description: Push inline code block snippets out of articles into standalone files with proper project structure. --- @@ -8,12 +10,14 @@ description: Push inline code block snippets out of articles into standalone fil **IMPORTANT**: Don't share code across multiple articles. Each article should have its own copy of the snippet in its own folder structure. +**IMPORTANT**: If only XAML snippets are present, only create C# projects to hold the XAML. Do not create VB projects for XAML-only snippets. + ## Quick Reference **WHEN TO PUSH:** Code >6 lines, complete/compilable examples, or when specifically requested -**FOLDER PATTERN:** `./snippets/{doc-file}/{csharp|vb}/` -**PROJECT CREATION:** Always use the `dotnet new console` command to create a new project for the code language -**LANGUAGES:** Create both C# and Visual Basic versions (if applicable). +**FOLDER PATTERN:** `./snippets/{doc-file}/[net-or-framework]/{csharp|vb}/` +**PROJECT CREATION:** Always use `dotnet new {winforms|wpf|console|classlib}` commands to create a new project for the code language +**LANGUAGES:** Create both C# and VB versions **SNIPPET IDs:** Use CamelCase region markers like `` **ARTICLE REFS:** Replace with `:::code language="csharp" source="./path" id="SnippetId":::` @@ -26,9 +30,9 @@ description: Push inline code block snippets out of articles into standalone fil - User specifically requests snippet extraction **KEEP INLINE WHEN:** -- Code blocks are 6 lines or shorter (unless you find an example in the article's snippets folder) -- Code shows configuration snippets (XAML, JSON, XML) (unless you find an example in the article's snippets folder) -- Code demonstrates simple one-liner examples (unless you find an example in the article's snippets folder) +- Code blocks are 6 lines or shorter +- Code shows configuration snippets (XAML, JSON, XML) +- XAML snippets that are more than 3 lines - Code is pseudo-code or conceptual examples ## Target folder structure @@ -36,21 +40,44 @@ description: Push inline code block snippets out of articles into standalone fil **IMPORTANT**: Follow a folder structure based on the article and code language: ### New snippet location (standard) -- Path pattern: `./snippets/{doc-file}/{code-language}/` -- Example: `./snippets/create-windows-forms-app/csharp/` +- Path pattern: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` +- Example: `./snippets/create-windows-forms-app/net/csharp/` **Path components explained:** - `{doc-file}`: The markdown article filename WITHOUT the `.md` extension - Example: For article `create-windows-forms-app.md` → use `create-windows-forms-app` +- `[net-or-framework]`: Choose based on target framework: + - `net`: For .NET (.NET 6 and newer) + - `framework`: For .NET Framework (4.8 and older) + - **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches. Otherwise, omit this folder. When in doubt, ask. - `{code-language}`: - - `csharp`: For C# code + - `csharp`: For C# code or when demonstrating XAML - `vb`: For Visual Basic code +## Framework targeting and project types + +**Determine target framework:** +- Check article frontmatter `ms.service` value: + - `dotnet-framework` → .NET Framework 4.8 + - `dotnet-desktop` → Current .NET (e.g., .NET 10) +- Examine code patterns and article content + +**Create appropriate project with `dotnet new`:** + +| Project Type | Indicators | .NET Command | .NET Framework Command | +|--------------|------------|--------------|------------------------| +| **Windows Forms** | `System.Windows.Forms`, `Form`, `/winforms/` path | `dotnet new winforms` | `dotnet new winforms --framework net48` | +| **WPF** | `System.Windows`, `Window`, XAML, `/wpf/` path | `dotnet new wpf` | `dotnet new wpf --framework net48` | +| **Console** | `Console.WriteLine`, simple examples, no UI | `dotnet new console` | `dotnet new console --framework net48` | +| **Class Library** | Reusable components, no entry point | `dotnet new classlib` | `dotnet new classlib --framework net48` | + ## Push process ### 1. Analyze and prepare -- Locate code to migrate -- Create folder structure: `./snippets/{doc-file}/{csharp|vb}/` +- Locate code blocks >6 lines or complete examples (unless overridden by user request) +- Determine project type from code patterns and article location +- Check framework targeting from frontmatter +- Create folder structure: `./snippets/{doc-file}/[net-or-framework]/{csharp|vb}/` ### 2. Create projects and extract code - Run appropriate `dotnet new` command in each language folder, **don't** specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible @@ -58,20 +85,21 @@ description: Push inline code block snippets out of articles into standalone fil - Add missing using statements, namespaces, class declarations - Modernize code patterns if targeting current .NET - Test compilation with `dotnet build` +- If snippets are XAML-based, store them in a C# project ### 3. Add snippet references and update article - Add CamelCase region markers: `// ` and `// ` - Use same identifiers across C# and VB versions - Replace inline code with snippet references: ```markdown - :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: - :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: + :::code language="xaml" source="./snippets/doc-name/net/csharp/File.xaml" id="ButtonClick"::: + :::code language="csharp" source="./snippets/doc-name/net/csharp/File.cs" id="ButtonClick"::: + :::code language="vb" source="./snippets/doc-name/net/vb/File.vb" id="ButtonClick"::: ``` - DO NOT use language tabs, simply put them side-by-side - Verify all paths and references are correct ### 4. Make sure frontmatter specifies a language when required - If both CSharp and VB examples are provided make sure the following frontmatter is at the top of the article: ```yml @@ -80,6 +108,8 @@ dev_langs: - "vb" ``` +If just XAML is provided, don't use a `dev_langs` section. + ## Common mistakes to avoid - ❌ Extracting short snippets (≤6 lines) without request diff --git a/.github/prompts/Snippets.Upgrade.prompt.md b/.github/prompts/Snippets.Upgrade.prompt.md new file mode 100644 index 0000000000000..925ab2397f0e3 --- /dev/null +++ b/.github/prompts/Snippets.Upgrade.prompt.md @@ -0,0 +1,111 @@ +--- +agent: agent +model: Claude Sonnet 4 (copilot) +description: Upgrade snippets to the latest .NET and possibly migrate from .NET Framework +--- + +# Code Snippet Upgrade Instructions + +## When to Apply These Instructions + +Apply these instructions when working with code snippets that need modernization, especially when: +- Migrating snippets from old locations +- Upgrading .NET Framework code to modern .NET +- Improving snippet quality and completeness +- Adding missing language versions (C# or VB) + +## Snippet Structure Requirements + +All snippets must follow this folder structure relative to the referencing article: + +``` +./snippets/{article-name}/[net|framework]/{language}/ +``` + +**Examples:** +- `./snippets/how-to-add-data-to-the-clipboard/net/csharp/MainForm.cs` +- `./snippets/how-to-add-data-to-the-clipboard/framework/vb/MainForm.vb` + +## Required Upgrade Actions + +### 1. File Naming and Organization +- **USE** PascalCase for class names and file names (e.g., `MainForm.cs`, `DataProcessor.cs`) +- **ORGANIZE** files logically within the language folder + +### 2. Snippet Identifiers and Naming +- **USE** meaningful, descriptive snippet identifiers in CamelCase format +- **REPLACE** simplistic identifiers (like single numbers) with descriptive snippet names +- **EXAMPLES** of good snippet identifiers: + - `BasicClipboardData` instead of `1` + - `CustomDataFormat` instead of `2` + - `ClipboardImageHandling` instead of `code1` +- **ENSURE** snippet identifiers clearly describe the code's purpose or functionality + +### 3. .NET Version and Syntax Modernization +- **TARGET** the latest stable .NET version for `/net/` folders +- **USE** modern C# features for .NET snippets: + - File-scoped namespaces + - Top-level statements where appropriate + - Pattern matching + - String interpolation + - var keyword where type is obvious + - Modern using statements + +### 4. Project File Requirements +- **USE** `dotnet new` to create the projects. Fallback to manual project creation if `dotnet new` is failing. +- **CREATE** a complete, compilable project structure +- **INCLUDE** appropriate `.csproj` or `.vbproj` file +- **TARGET** latest .NET version: `net8.0-windows` +- **ADD** necessary package references and properties + +### 5. Code Quality Standards +- **ENSURE** code compiles without warnings +- **FOLLOW** .NET naming conventions +- **USE** appropriate access modifiers +- **INCLUDE** necessary using/import statements +- **ADD** minimal but helpful code comments for complex logic + +### 6. Language Parity +- **CREATE** both C# and VB.NET versions unless the parent article is in a language-specific folder +- **MAINTAIN** functional equivalence between language versions +- **ADAPT** language-specific idioms appropriately + +## Framework-Specific Considerations + +### For .NET Framework Snippets (`/framework/` folders) +- **MAINTAIN** .NET Framework compatibility +- **AVOID** modern C# features not available in the target framework version +- **USE** classic C# syntax and patterns +- **TARGET** appropriate framework version (typically .NET Framework 4.8) + +### For Modern .NET Snippets (`/net/` folders) +- **USE** latest .NET features and syntax +- **TARGET** latest stable .NET version +- **LEVERAGE** modern performance patterns +- **UTILIZE** new APIs where beneficial + +## Example Transformation + +**Before (simple identifier):** +``` +./snippets/clipboard-article/code.cs +``` + +**After (descriptive structure):** +``` +./snippets/how-to-add-data-to-the-clipboard/net/csharp/ +├── ClipboardExample.csproj +├── MainForm.cs +└── Program.cs +``` + +## Validation Checklist + +Before completing snippet upgrades, verify: +- [ ] Files have descriptive, meaningful names +- [ ] Project compiles without errors or warnings +- [ ] Code follows .NET naming conventions +- [ ] Appropriate target framework is specified +- [ ] Both C# and VB versions exist (when required) +- [ ] Modern syntax is used for .NET snippets +- [ ] Framework-compatible syntax for .NET Framework snippets \ No newline at end of file From 74fb13c1a22ff00d23ce01eed4746d317cb5deb5 Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 13 Mar 2026 14:01:14 -0700 Subject: [PATCH 2/8] Update instructions --- .github/prompts/Snippets.Migrate.prompt.md | 108 +++++++------------ .github/prompts/Snippets.Push.prompt.md | 118 +++++++++------------ .github/prompts/Snippets.Upgrade.prompt.md | 115 ++++++++++---------- 3 files changed, 140 insertions(+), 201 deletions(-) diff --git a/.github/prompts/Snippets.Migrate.prompt.md b/.github/prompts/Snippets.Migrate.prompt.md index 1632efccfc391..c1fd019396367 100644 --- a/.github/prompts/Snippets.Migrate.prompt.md +++ b/.github/prompts/Snippets.Migrate.prompt.md @@ -1,11 +1,13 @@ --- agent: agent -model: Claude Sonnet 4 (copilot) +model: Claude Sonnet 4.6 (copilot) description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location. --- # Migrate code snippets +We no longer use the `~/samples/snippets/` location for code snippets. All code snippets must be migrated to the new `./snippets/` location, which is relative to the article using the snippet. Generally, snippets in the old location are outdated, incomplete, and often can't compile. The new location requires that all snippets be complete, compilable, and include project files. Additionally, the new location requires both C# and Visual Basic versions of each snippet. + **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 @@ -15,45 +17,38 @@ description: Migrate code from the old ~/samples/snippets/ location to the relat ### 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}/[net-or-framework]/{code-language}/` -- Example: `./snippets/how-to-add-data-to-the-clipboard/net/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` -- `[net-or-framework]`: Choose based on target framework: - - `net`: For .NET (.NET 6 and newer) - - `framework`: For .NET Framework (4.8 and older) - - **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches -- `{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:** - Written for .NET Framework (outdated) -- Often incomplete or non-compilable +- Often incomplete and can't compile - May lack project files - Uses outdated syntax and patterns -**Legacy article references look like this:** +**Legacy article references generally use old syntax:** ```markdown [!code-{code-language}[description](~/samples/snippets/{path-to-file}#{snippet-identifier})] ``` +### New location (current standard - migrate TO) +- Path pattern: `./snippets/{article-filename-using-snippet}/[optional-sub-subject]/{code-language}/` +- Example C#: `./snippets/anchors-in-regular-expressions/csharp/form1.cs` +- Example VB: `./snippets/anchors-in-regular-expressions/vb/form1.vb` -## Current code requirements (migrate TO these) +**Path components explained:** +- `./`: Current folder of the article being edited +- `snippets/`: Root folder for all snippets +- `{article-filename-using-snippet}`: The markdown article filename WITHOUT the `.md` extension + - Example: For article `anchors-in-regular-expressions.md` → use `anchors-in-regular-expressions` +- `[optional-sub-subject]`: An optional subfolder to avoid clashes. Used when a snippet in the article can't be merged with existing snippets. Examples of this would be two different snippets that both use a `Program.cs` file. For example, if there were two snippets in the same file demonstrating an Async `main` and a non-Async `main`, you could create descriptive subfolders like `AsyncProgram/` and `SyncProgram/` to avoid conflicts. +- `{code-language}`: + - `csharp`: For C# code + - `vb`: For Visual Basic code -**Location**: `./snippets/{doc-file}/[framework]/{code-language}/` +**IMPORTANT**: Exception to the rules about having multiple code languages: For language guide articles, only the guide's language is required — do not create a version in the other language. The C# Language guide only contains CS code snippets, and the VB Language guide only contains VB code snippets. All other articles should follow the full path pattern including the `{code-language}/` subfolder. For example, you wouldn't use the `./snippets/article-name/csharp/` or `./snippets/article-name/vb/` folder structures for an article in the C# language guide, the folder would simply be `./snippets/article-name/` and the code in C#. The same applies to the VB language guide. **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 target the latest .NET version - ✅ 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 @@ -62,82 +57,55 @@ description: Migrate code from the old ~/samples/snippets/ location to the relat **Current article references look like this:** ```markdown -:::code language="{code-language}" source="{file-path}" id="{snippet-identifier}"::: +:::code language="{code-language}" source="{relative-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 migrate only**: When article has `ms.service: dotnet-framework` frontmatter or is specifically about .NET Framework features -- **When to modernize**: When article demonstrates both .NET and .NET Framework, or when specifically requested -- **Default targeting**: - - For .NET Framework-specific articles: Keep targeting .NET Framework - - For general articles: Target latest .NET version (e.g., .NET 10) - - For mixed articles: Create separate snippets in `net/` and `framework/` subfolders - ## 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/` -- **Check frontmatter**: Look for `ms.service: dotnet-framework` in the article's frontmatter -- **Determine scope**: - - If frontmatter has `ms.service: dotnet-framework` → this is likely a .NET Framework-specific article - - if frontmatter has `ms.service: dotnet-desktop` or similar → this is likely a dual-framework or general article - - If article demonstrates both .NET and .NET Framework → prepare for dual targeting - - If article is general purpose → consider targeting current .NET +- **Find**: Locate the legacy snippet file references to `~/samples/snippets/` (path may be relative, navigating back to the root `samples` folder) - **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}/[net-or-framework]/{code-language}/` -- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/net/csharp/` -- **Decision tree for framework folder**: - - Article has `ms.service: dotnet-framework` frontmatter → use `./snippets/{doc-file}/framework/{code-language}/` - - Article shows ONLY current .NET examples → use `./snippets/{doc-file}/{code-language}/` (omit framework folder) - - Article shows BOTH .NET and .NET Framework → create both `./snippets/{doc-file}/net/{code-language}/` and `./snippets/{doc-file}/framework/{code-language}/` +### 2. Create new or reuse existing folder structure +- **Pattern**: `./snippets/{article-filename-using-snippet}/[optional-sub-subject]/{code-language}/` +- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/csharp/` +- **Reuse**: If the article already has snippets in the new location, reuse the existing folder structure and try to merge the code into the existing snippets if possible. Use new classes and code files as needed. Code **ONLY** needs to compile, it doesn't have to run from the program main. +- **Create**: If no existing folder structure exists for the article, create a new one following the pattern above. +- **New projects**: **NEVER** create project files manually. Always use the `dotnet` CLI to ensure correct formatting and structure of new code. Projects should be console apps unless otherwise required (such as a Windows Forms-related snippet) ### 3. Migrate and update code - **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location -- **Update approach**: - - **For .NET Framework articles**: Migrate with minimal changes, keep .NET Framework targeting - - **For dual-framework articles**: Create both versions with appropriate targeting and update frontmatter to `ms.service: dotnet-desktop` - - **For general articles**: Update to target current .NET only if specifically requested or if article demonstrates modernization - **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}/[framework]/csharp/` -- **VB path**: `./snippets/{doc-file}/[framework]/vb/` +- **Requirement**: MUST provide both C# and Visual Basic versions, except for language guide articles (C# or VB guide), where only the guide's language is required. +- **Standard articles** (both languages required): + - **C# path**: `./snippets/{article-filename-using-snippet}/csharp/` + - **VB path**: `./snippets/{article-filename-using-snippet}/vb/` +- **Language guide articles** (single language, no `{code-language}` subfolder): + - **C# guide path**: `./snippets/{article-filename-using-snippet}/` + - **VB guide path**: `./snippets/{article-filename-using-snippet}/` ### 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/net/csharp/file.cs" id="BasicClipboardData":::` +- **After**: `:::code language="csharp" source="./snippets/article-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 -- **Clean**: Remove unused legacy files (if no other articles reference them) ### 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. + - Check if the old snippet file is used by any other articles. Search for the old snippet path across the repository to find any references. This can be done by searching for links to `samples/snippets/...` (the file path used in the snippet reference) since some articles may use a relative path to the `samples` folder instead of absolute paths. +- **Delete**: If old snippet was migrated and is no longer used by any other 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** ignore the `ms.service: dotnet-framework` frontmatter indicator - ❌ **Don't** forget to create both C# and VB versions - ❌ **Don't** mix up the framework targeting (net vs framework) - ❌ **Don't** forget to update ALL article references to the migrated code diff --git a/.github/prompts/Snippets.Push.prompt.md b/.github/prompts/Snippets.Push.prompt.md index d3ef3398086cf..5c176e6dac5d8 100644 --- a/.github/prompts/Snippets.Push.prompt.md +++ b/.github/prompts/Snippets.Push.prompt.md @@ -1,6 +1,6 @@ --- agent: agent -model: Claude Sonnet 4 (copilot) +model: Claude Sonnet 4.6 (copilot) description: Push inline code block snippets out of articles into standalone files with proper project structure. --- @@ -15,92 +15,78 @@ description: Push inline code block snippets out of articles into standalone fil ## Quick Reference **WHEN TO PUSH:** Code >6 lines, complete/compilable examples, or when specifically requested -**FOLDER PATTERN:** `./snippets/{doc-file}/[net-or-framework]/{csharp|vb}/` -**PROJECT CREATION:** Always use `dotnet new {winforms|wpf|console|classlib}` commands to create a new project for the code language -**LANGUAGES:** Create both C# and VB versions +**FOLDER PATTERN:** `./snippets/{doc-file}/[optional-sub-subject]/{csharp|vb}/` +**PROJECT CREATION:** Always use `dotnet new` CLI commands — never create project files manually. Default to console apps. +**LANGUAGES:** Create both C# and VB versions (see language guide exception below) **SNIPPET IDs:** Use CamelCase region markers like `` **ARTICLE REFS:** Replace with `:::code language="csharp" source="./path" id="SnippetId":::` ## When to push snippets out of articles **PUSH SNIPPETS WHEN:** -- Code blocks are longer than 6 lines or the rest of the article is using them +- Code blocks are longer than 6 lines - Code demonstrates complete, compilable examples - Code represents a complete application or significant functionality - User specifically requests snippet extraction **KEEP INLINE WHEN:** - Code blocks are 6 lines or shorter -- Code shows configuration snippets (XAML, JSON, XML) -- XAML snippets that are more than 3 lines - Code is pseudo-code or conceptual examples ## Target folder structure -**IMPORTANT**: Follow a folder structure based on the article and code language: - -### New snippet location (standard) -- Path pattern: `./snippets/{doc-file}/[net-or-framework]/{code-language}/` -- Example: `./snippets/create-windows-forms-app/net/csharp/` +- Path pattern: `./snippets/{doc-file}/[optional-sub-subject]/{code-language}/` +- Example C#: `./snippets/create-app/csharp/` +- Example VB: `./snippets/create-app/vb/` **Path components explained:** +- `./`: Current folder of the article being edited +- `snippets/`: Root folder for all snippets - `{doc-file}`: The markdown article filename WITHOUT the `.md` extension - - Example: For article `create-windows-forms-app.md` → use `create-windows-forms-app` -- `[net-or-framework]`: Choose based on target framework: - - `net`: For .NET (.NET 6 and newer) - - `framework`: For .NET Framework (4.8 and older) - - **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches. Otherwise, omit this folder. When in doubt, ask. -- `{code-language}`: - - `csharp`: For C# code or when demonstrating XAML + - Example: For article `create-app.md` → use `create-app` +- `[optional-sub-subject]`: An optional subfolder to avoid clashes. Used when snippets in the same article can't be merged — for example, two snippets that both require a `Program.cs` file but demonstrate different things. Use descriptive subfolder names like `AsyncProgram/` and `SyncProgram/`. +- `{code-language}`: + - `csharp`: For C# code (also use for XAML snippets) - `vb`: For Visual Basic code -## Framework targeting and project types - -**Determine target framework:** -- Check article frontmatter `ms.service` value: - - `dotnet-framework` → .NET Framework 4.8 - - `dotnet-desktop` → Current .NET (e.g., .NET 10) -- Examine code patterns and article content - -**Create appropriate project with `dotnet new`:** - -| Project Type | Indicators | .NET Command | .NET Framework Command | -|--------------|------------|--------------|------------------------| -| **Windows Forms** | `System.Windows.Forms`, `Form`, `/winforms/` path | `dotnet new winforms` | `dotnet new winforms --framework net48` | -| **WPF** | `System.Windows`, `Window`, XAML, `/wpf/` path | `dotnet new wpf` | `dotnet new wpf --framework net48` | -| **Console** | `Console.WriteLine`, simple examples, no UI | `dotnet new console` | `dotnet new console --framework net48` | -| **Class Library** | Reusable components, no entry point | `dotnet new classlib` | `dotnet new classlib --framework net48` | +**Language guide exception**: For articles in the C# or VB language guides, only the guide's language is required — do not create a version in the other language, and omit the `{code-language}/` subfolder: +- C# guide path: `./snippets/{doc-file}/` +- VB guide path: `./snippets/{doc-file}/` ## Push process ### 1. Analyze and prepare - Locate code blocks >6 lines or complete examples (unless overridden by user request) -- Determine project type from code patterns and article location -- Check framework targeting from frontmatter -- Create folder structure: `./snippets/{doc-file}/[net-or-framework]/{csharp|vb}/` +- Identify the programming language(s) used +- Determine if the article is in a language guide (C# or VB) to apply the language exception ### 2. Create projects and extract code -- Run appropriate `dotnet new` command in each language folder, **don't** specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible -- Copy and complete code to make it compilable -- Add missing using statements, namespaces, class declarations -- Modernize code patterns if targeting current .NET -- Test compilation with `dotnet build` -- If snippets are XAML-based, store them in a C# project - -### 3. Add snippet references and update article -- Add CamelCase region markers: `// ` and `// ` -- Use same identifiers across C# and VB versions -- Replace inline code with snippet references: +- **NEVER** create project files manually. Always use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type (for example, `dotnet new winforms` for a Windows Forms snippet). Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible. +- Copy and complete code to make it compilable. Code only needs to compile — it doesn't have to run from `Main`. +- Add missing using statements, namespaces, and class declarations as needed. +- Build to verify compilation with `dotnet build`. + +### 3. Add snippet markers and update article references +- Add CamelCase region markers around each snippet: + - C#: `// ` and `// ` + - VB: `' ` and `' ` +- Use the same identifiers across C# and VB versions. +- Use meaningful, descriptive identifiers — avoid `1`, `2`, `code1`, or `snippet1`. +- Replace each inline code block with a `:::code:::` reference: ```markdown - :::code language="xaml" source="./snippets/doc-name/net/csharp/File.xaml" id="ButtonClick"::: - :::code language="csharp" source="./snippets/doc-name/net/csharp/File.cs" id="ButtonClick"::: - :::code language="vb" source="./snippets/doc-name/net/vb/File.vb" id="ButtonClick"::: + :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="SnippetId"::: + :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="SnippetId"::: ``` -- DO NOT use language tabs, simply put them side-by-side -- Verify all paths and references are correct +- DO NOT use language tabs — place references side-by-side, like so: + ```markdown + :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="SnippetId"::: + + :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="SnippetId"::: + ``` +- Verify all paths and identifiers are correct. -### 4. Make sure frontmatter specifies a language when required -If both CSharp and VB examples are provided make sure the following frontmatter is at the top of the article: +### 4. Update article frontmatter +If both C# and VB examples are provided, ensure the following frontmatter is present at the top of the article: ```yml dev_langs: @@ -108,22 +94,14 @@ dev_langs: - "vb" ``` -If just XAML is provided, don't use a `dev_langs` section. +If a single language is used (like in the language guides), omit the `dev_langs` section. ## Common mistakes to avoid -- ❌ Extracting short snippets (≤6 lines) without request -- ❌ Skipping `dotnet new` commands or creating incomplete projects -- ❌ Missing C# or VB versions -- ❌ Using language tabs -- ❌ Wrong project type (winforms vs wpf vs console) -- ❌ Incorrect framework targeting (net vs framework) +- ❌ Extracting short snippets (≤6 lines) without being asked +- ❌ Creating project files manually instead of using `dotnet new` +- ❌ Missing C# or VB versions for standard articles +- ❌ Creating VB projects for XAML-only snippets +- ❌ Using language tabs instead of side-by-side references - ❌ Missing or inconsistent snippet region identifiers - ❌ Code that doesn't compile - -## Quality checklist - -- ✅ Correct folder structure and project type -- ✅ Both C# and VB versions compile successfully -- ✅ Snippet regions use CamelCase identifiers -- ✅ Article uses correct `:::code...:::` syntax with valid paths \ No newline at end of file diff --git a/.github/prompts/Snippets.Upgrade.prompt.md b/.github/prompts/Snippets.Upgrade.prompt.md index 925ab2397f0e3..c75faddda4672 100644 --- a/.github/prompts/Snippets.Upgrade.prompt.md +++ b/.github/prompts/Snippets.Upgrade.prompt.md @@ -1,6 +1,6 @@ --- agent: agent -model: Claude Sonnet 4 (copilot) +model: Claude Sonnet 4.6 (copilot) description: Upgrade snippets to the latest .NET and possibly migrate from .NET Framework --- @@ -9,9 +9,8 @@ description: Upgrade snippets to the latest .NET and possibly migrate from .NET ## When to Apply These Instructions Apply these instructions when working with code snippets that need modernization, especially when: -- Migrating snippets from old locations -- Upgrading .NET Framework code to modern .NET - Improving snippet quality and completeness +- Upgrading .NET Framework code to modern .NET - Adding missing language versions (C# or VB) ## Snippet Structure Requirements @@ -19,93 +18,87 @@ Apply these instructions when working with code snippets that need modernization All snippets must follow this folder structure relative to the referencing article: ``` -./snippets/{article-name}/[net|framework]/{language}/ +./snippets/{article-name}/[optional-sub-subject]/{code-language}/ ``` +**Path components explained:** +- `./`: Current folder of the article being edited +- `snippets/`: Root folder for all snippets +- `{article-name}`: The markdown article filename WITHOUT the `.md` extension +- `[optional-sub-subject]`: An optional subfolder to avoid clashes — use when two snippets in the same article can't be merged (for example, both require a `Program.cs` file). Use descriptive names like `AsyncProgram/` and `SyncProgram/`. +- `{code-language}`: `csharp` for C#, `vb` for Visual Basic + **Examples:** -- `./snippets/how-to-add-data-to-the-clipboard/net/csharp/MainForm.cs` -- `./snippets/how-to-add-data-to-the-clipboard/framework/vb/MainForm.vb` +- `./snippets/how-to-add-data-to-the-clipboard/csharp/MainForm.cs` +- `./snippets/how-to-add-data-to-the-clipboard/vb/MainForm.vb` + +**Language guide exception**: For articles in the C# or VB language guides, only the guide's language is required — do not create a version in the other language, and omit the `{code-language}/` subfolder. The path is simply `./snippets/{article-name}/`. ## Required Upgrade Actions ### 1. File Naming and Organization -- **USE** PascalCase for class names and file names (e.g., `MainForm.cs`, `DataProcessor.cs`) -- **ORGANIZE** files logically within the language folder +- Use PascalCase for class names and file names (e.g., `MainForm.cs`, `DataProcessor.cs`) +- Organize files logically within the language folder ### 2. Snippet Identifiers and Naming -- **USE** meaningful, descriptive snippet identifiers in CamelCase format -- **REPLACE** simplistic identifiers (like single numbers) with descriptive snippet names -- **EXAMPLES** of good snippet identifiers: - - `BasicClipboardData` instead of `1` - - `CustomDataFormat` instead of `2` - - `ClipboardImageHandling` instead of `code1` -- **ENSURE** snippet identifiers clearly describe the code's purpose or functionality - -### 3. .NET Version and Syntax Modernization -- **TARGET** the latest stable .NET version for `/net/` folders -- **USE** modern C# features for .NET snippets: +- Use meaningful, descriptive snippet identifiers in CamelCase format +- Replace simplistic identifiers (like single numbers) with descriptive names +- Good examples: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling` +- Avoid: `1`, `2`, `code1`, `snippet1` +- Identifiers should clearly describe the code's purpose or functionality + +### 3. Syntax Modernization +- Target the latest stable .NET version +- Use modern C# features: - File-scoped namespaces - Top-level statements where appropriate - Pattern matching - String interpolation - - var keyword where type is obvious - - Modern using statements + - `var` where type is obvious + - Modern `using` statements ### 4. Project File Requirements -- **USE** `dotnet new` to create the projects. Fallback to manual project creation if `dotnet new` is failing. -- **CREATE** a complete, compilable project structure -- **INCLUDE** appropriate `.csproj` or `.vbproj` file -- **TARGET** latest .NET version: `net8.0-windows` -- **ADD** necessary package references and properties +- **NEVER** create project files manually. Always use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type. Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible. +- Ensure a complete, compilable project structure with an appropriate `.csproj` or `.vbproj` file +- Code only needs to compile — it doesn't have to run from `Main` +- Verify compilation with `dotnet build` ### 5. Code Quality Standards -- **ENSURE** code compiles without warnings -- **FOLLOW** .NET naming conventions -- **USE** appropriate access modifiers -- **INCLUDE** necessary using/import statements -- **ADD** minimal but helpful code comments for complex logic +- Ensure code compiles without errors +- Follow .NET naming conventions +- Use appropriate access modifiers +- Include necessary `using`/`import` statements ### 6. Language Parity -- **CREATE** both C# and VB.NET versions unless the parent article is in a language-specific folder -- **MAINTAIN** functional equivalence between language versions -- **ADAPT** language-specific idioms appropriately - -## Framework-Specific Considerations - -### For .NET Framework Snippets (`/framework/` folders) -- **MAINTAIN** .NET Framework compatibility -- **AVOID** modern C# features not available in the target framework version -- **USE** classic C# syntax and patterns -- **TARGET** appropriate framework version (typically .NET Framework 4.8) - -### For Modern .NET Snippets (`/net/` folders) -- **USE** latest .NET features and syntax -- **TARGET** latest stable .NET version -- **LEVERAGE** modern performance patterns -- **UTILIZE** new APIs where beneficial +- Create both C# and VB.NET versions for standard articles +- For language guide articles (C# or VB guide), only the guide's language is required +- Maintain functional equivalence between language versions +- Adapt language-specific idioms appropriately ## Example Transformation -**Before (simple identifier):** +**Before (outdated structure):** ``` -./snippets/clipboard-article/code.cs +~/samples/snippets/csharp/clipboard/code.cs ``` -**After (descriptive structure):** +**After (current structure):** ``` -./snippets/how-to-add-data-to-the-clipboard/net/csharp/ +./snippets/how-to-add-data-to-the-clipboard/csharp/ ├── ClipboardExample.csproj ├── MainForm.cs └── Program.cs + +./snippets/how-to-add-data-to-the-clipboard/vb/ +├── ClipboardExample.vbproj +├── MainForm.vb +└── Program.vb ``` -## Validation Checklist +## Common mistakes to avoid -Before completing snippet upgrades, verify: -- [ ] Files have descriptive, meaningful names -- [ ] Project compiles without errors or warnings -- [ ] Code follows .NET naming conventions -- [ ] Appropriate target framework is specified -- [ ] Both C# and VB versions exist (when required) -- [ ] Modern syntax is used for .NET snippets -- [ ] Framework-compatible syntax for .NET Framework snippets \ No newline at end of file +- ❌ Using the old `[net|framework]` subfolder in paths +- ❌ Creating project files manually instead of using `dotnet new` +- ❌ Missing C# or VB versions for standard articles +- ❌ Using simplistic or non-descriptive snippet identifiers +- ❌ Code that doesn't compile \ No newline at end of file From 9640ad8551c623e9c6857876190e086e2ed9f315 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 13 Mar 2026 14:10:19 -0700 Subject: [PATCH 3/8] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .github/prompts/Snippets.Push.prompt.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/prompts/Snippets.Push.prompt.md b/.github/prompts/Snippets.Push.prompt.md index 5c176e6dac5d8..7c5e4a7a4f0bb 100644 --- a/.github/prompts/Snippets.Push.prompt.md +++ b/.github/prompts/Snippets.Push.prompt.md @@ -70,18 +70,19 @@ description: Push inline code block snippets out of articles into standalone fil - Add CamelCase region markers around each snippet: - C#: `// ` and `// ` - VB: `' ` and `' ` +- The angle brackets (`<` and `>`) are part of the comment markers only. The snippet identifier itself is the bare CamelCase name (for example, `ButtonClick`), which is what you use in the `id` attribute. - Use the same identifiers across C# and VB versions. - Use meaningful, descriptive identifiers — avoid `1`, `2`, `code1`, or `snippet1`. - Replace each inline code block with a `:::code:::` reference: ```markdown - :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="SnippetId"::: - :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="SnippetId"::: + :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: + :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: ``` - DO NOT use language tabs — place references side-by-side, like so: ```markdown - :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="SnippetId"::: + :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: - :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="SnippetId"::: + :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: ``` - Verify all paths and identifiers are correct. From dc3722c646b5ece7db8e4eefc75029d56dbdf31d Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 13 Mar 2026 14:10:37 -0700 Subject: [PATCH 4/8] Minor updates before pulling --- .github/prompts/Snippets.Push.prompt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/prompts/Snippets.Push.prompt.md b/.github/prompts/Snippets.Push.prompt.md index 5c176e6dac5d8..a588a3f90655d 100644 --- a/.github/prompts/Snippets.Push.prompt.md +++ b/.github/prompts/Snippets.Push.prompt.md @@ -6,7 +6,7 @@ description: Push inline code block snippets out of articles into standalone fil # Push inline code snippets to files -**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 that might benefit from the same snippet extraction. +**IMPORTANT**: Unless otherwise asked to, **only** extract snippets from the article file in context. At the end of your operations you may ask for permission to edit other articles that might benefit from the same snippet extraction. **IMPORTANT**: Don't share code across multiple articles. Each article should have its own copy of the snippet in its own folder structure. From 5807da6dafa14bc64754e70b06b1a989ffb528ba Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Fri, 13 Mar 2026 14:22:03 -0700 Subject: [PATCH 5/8] Feedback --- .github/prompts/Snippets.Migrate.prompt.md | 4 ++-- .github/prompts/Snippets.Push.prompt.md | 21 ++++++--------------- 2 files changed, 8 insertions(+), 17 deletions(-) diff --git a/.github/prompts/Snippets.Migrate.prompt.md b/.github/prompts/Snippets.Migrate.prompt.md index c1fd019396367..8d43796bcc0f7 100644 --- a/.github/prompts/Snippets.Migrate.prompt.md +++ b/.github/prompts/Snippets.Migrate.prompt.md @@ -30,8 +30,8 @@ We no longer use the `~/samples/snippets/` location for code snippets. All code ``` ### New location (current standard - migrate TO) - Path pattern: `./snippets/{article-filename-using-snippet}/[optional-sub-subject]/{code-language}/` -- Example C#: `./snippets/anchors-in-regular-expressions/csharp/form1.cs` -- Example VB: `./snippets/anchors-in-regular-expressions/vb/form1.vb` +- Example C#: `./snippets/anchors-in-regular-expressions/csharp/Form1.cs` +- Example VB: `./snippets/anchors-in-regular-expressions/vb/Form1.vb` **Path components explained:** - `./`: Current folder of the article being edited diff --git a/.github/prompts/Snippets.Push.prompt.md b/.github/prompts/Snippets.Push.prompt.md index 005c70851645e..3b8ebe44855c4 100644 --- a/.github/prompts/Snippets.Push.prompt.md +++ b/.github/prompts/Snippets.Push.prompt.md @@ -12,15 +12,6 @@ description: Push inline code block snippets out of articles into standalone fil **IMPORTANT**: If only XAML snippets are present, only create C# projects to hold the XAML. Do not create VB projects for XAML-only snippets. -## Quick Reference - -**WHEN TO PUSH:** Code >6 lines, complete/compilable examples, or when specifically requested -**FOLDER PATTERN:** `./snippets/{doc-file}/[optional-sub-subject]/{csharp|vb}/` -**PROJECT CREATION:** Always use `dotnet new` CLI commands — never create project files manually. Default to console apps. -**LANGUAGES:** Create both C# and VB versions (see language guide exception below) -**SNIPPET IDs:** Use CamelCase region markers like `` -**ARTICLE REFS:** Replace with `:::code language="csharp" source="./path" id="SnippetId":::` - ## When to push snippets out of articles **PUSH SNIPPETS WHEN:** @@ -35,14 +26,14 @@ description: Push inline code block snippets out of articles into standalone fil ## Target folder structure -- Path pattern: `./snippets/{doc-file}/[optional-sub-subject]/{code-language}/` +- Path pattern: `./snippets/{article-name}/[optional-sub-subject]/{code-language}/` - Example C#: `./snippets/create-app/csharp/` - Example VB: `./snippets/create-app/vb/` **Path components explained:** - `./`: Current folder of the article being edited - `snippets/`: Root folder for all snippets -- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension +- `{article-name}`: The markdown article filename WITHOUT the `.md` extension - Example: For article `create-app.md` → use `create-app` - `[optional-sub-subject]`: An optional subfolder to avoid clashes. Used when snippets in the same article can't be merged — for example, two snippets that both require a `Program.cs` file but demonstrate different things. Use descriptive subfolder names like `AsyncProgram/` and `SyncProgram/`. - `{code-language}`: @@ -50,8 +41,8 @@ description: Push inline code block snippets out of articles into standalone fil - `vb`: For Visual Basic code **Language guide exception**: For articles in the C# or VB language guides, only the guide's language is required — do not create a version in the other language, and omit the `{code-language}/` subfolder: -- C# guide path: `./snippets/{doc-file}/` -- VB guide path: `./snippets/{doc-file}/` +- C# guide path: `./snippets/{article-name}/` +- VB guide path: `./snippets/{article-name}/` ## Push process @@ -67,10 +58,10 @@ description: Push inline code block snippets out of articles into standalone fil - Build to verify compilation with `dotnet build`. ### 3. Add snippet markers and update article references -- Add CamelCase region markers around each snippet: +- Add CamelCase region markers around each snippet. Snippet markers are added as comments in the language of the code file: - C#: `// ` and `// ` - VB: `' ` and `' ` -- The angle brackets (`<` and `>`) are part of the comment markers only. The snippet identifier itself is the bare CamelCase name (for example, `ButtonClick`), which is what you use in the `id` attribute. +- The angle brackets (`<` and `>`) are part of the comment markers only. The snippet identifier itself is the bare CamelCase name (for example, `SnippetId`), which is what you use in the `id` attribute. - Use the same identifiers across C# and VB versions. - Use meaningful, descriptive identifiers — avoid `1`, `2`, `code1`, or `snippet1`. - Replace each inline code block with a `:::code:::` reference: From 9ba79a4fc1591c2fec7e4f21ebad54ba911fb0de Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Tue, 17 Mar 2026 14:17:45 -0700 Subject: [PATCH 6/8] Revise guidelines for code snippet extraction --- .github/prompts/Snippets.Push.prompt.md | 30 +++++++++++++++++++------ 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/.github/prompts/Snippets.Push.prompt.md b/.github/prompts/Snippets.Push.prompt.md index 3b8ebe44855c4..7c45546f99ad9 100644 --- a/.github/prompts/Snippets.Push.prompt.md +++ b/.github/prompts/Snippets.Push.prompt.md @@ -25,7 +25,6 @@ description: Push inline code block snippets out of articles into standalone fil - Code is pseudo-code or conceptual examples ## Target folder structure - - Path pattern: `./snippets/{article-name}/[optional-sub-subject]/{code-language}/` - Example C#: `./snippets/create-app/csharp/` - Example VB: `./snippets/create-app/vb/` @@ -51,13 +50,30 @@ description: Push inline code block snippets out of articles into standalone fil - Identify the programming language(s) used - Determine if the article is in a language guide (C# or VB) to apply the language exception -### 2. Create projects and extract code -- **NEVER** create project files manually. Always use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type (for example, `dotnet new winforms` for a Windows Forms snippet). Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible. +### 2. Decide how code will be placed +- If the article talks about single-file apps, **STOP** and ask the user if they want to use a single-file app or a traditional project-based app +- If the article doesn't talk about single-file apps, assume the code samples must be put into a project-based app + +### 2.1 Project-based apps +- This is the default for moving code snippets from an article +- **NEVER** create project files manually. +- **ALWAYS** use the `dotnet` CLI. Default to console apps (`dotnet new console`) unless the snippet requires a different project type (for example, `dotnet new winforms` for a Windows Forms snippet). Don't specify an output folder with `-o`. Specify a meaningful project name with `-n` if possible. + +### 2.2 Single-file apps +- This is not the default. You must have a good reason to use this mode, such as the user requested it or the article itself references single-file apps along with the snippets +- Only C# is supported +- VB snippets must use a project-based app approach +- Multiple single-file apps can share the same folder for the article +- Instead of `Program.cs`, they can be named anything +- They are compiled with `dotnet run file.cs` +- Folder must not have a project file + +### 3. Extract code - Copy and complete code to make it compilable. Code only needs to compile — it doesn't have to run from `Main`. - Add missing using statements, namespaces, and class declarations as needed. - Build to verify compilation with `dotnet build`. -### 3. Add snippet markers and update article references +### 4. Add snippet markers and update article references - Add CamelCase region markers around each snippet. Snippet markers are added as comments in the language of the code file: - C#: `// ` and `// ` - VB: `' ` and `' ` @@ -69,7 +85,7 @@ description: Push inline code block snippets out of articles into standalone fil :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick"::: ``` -- DO NOT use language tabs — place references side-by-side, like so: +- DO NOT use language tabs in the article — place references side-by-side, like so: ```markdown :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick"::: @@ -77,7 +93,7 @@ description: Push inline code block snippets out of articles into standalone fil ``` - Verify all paths and identifiers are correct. -### 4. Update article frontmatter +### 5. Update article frontmatter If both C# and VB examples are provided, ensure the following frontmatter is present at the top of the article: ```yml @@ -91,7 +107,7 @@ If a single language is used (like in the language guides), omit the `dev_langs` ## Common mistakes to avoid - ❌ Extracting short snippets (≤6 lines) without being asked -- ❌ Creating project files manually instead of using `dotnet new` +- ❌ Creating project files manually instead of using `dotnet new` (when using project-based apps) - ❌ Missing C# or VB versions for standard articles - ❌ Creating VB projects for XAML-only snippets - ❌ Using language tabs instead of side-by-side references From b3016051cae8710038a7c0a92ac8278c1fb41bf3 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Tue, 17 Mar 2026 14:36:33 -0700 Subject: [PATCH 7/8] Enhance clarity guidelines in docseditor agent Added guidelines for replacing ambiguous 'this' references and ensuring consistent terminology. --- .github/agents/docseditor.agent.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/agents/docseditor.agent.md b/.github/agents/docseditor.agent.md index 43ca3d27e5116..f5a7208eb15fb 100644 --- a/.github/agents/docseditor.agent.md +++ b/.github/agents/docseditor.agent.md @@ -124,6 +124,15 @@ When editing, focus on these areas in order of priority: - ❌ Remove filler words: "quite", "very", "easily", "simply" (unless essential) - Look for ANY unnecessary prepositional phrases or filler words +**SCAN FOR AND REPLACE ambiguous "this" references (these are examples - find ALL similar patterns):** +- "This" at the start of a sentence or clause is often ambiguous — replace it with the specific noun it refers to +- ❌ "This creates a file" → ✅ "The command creates a file" +- ❌ "This is useful when..." → ✅ "The feature is useful when..." +- ❌ "This can be configured by..." → ✅ "The setting can be configured by..." +- ❌ "Configure this before deploying" → ✅ "Configure the connection string before deploying" +- Look for ANY sentence or clause where "this" starts or is the subject, and replace it with the explicit noun +- **NOTE:** "this" is acceptable when used as an adjective directly before a noun ("this method", "this file"), but avoid it when used alone as a pronoun + **SCAN FOR AND ENSURE consistent terminology (apply this principle throughout):** - Pick one term for each concept and use it throughout - ❌ "Because" and "Since" mixed → ✅ "Because" consistently @@ -219,6 +228,7 @@ After editing, you MUST verify: - [ ] ALL contractions added where appropriate - [ ] ALL verbose phrases simplified - [ ] ALL weak constructions eliminated +- [ ] ALL ambiguous "this" pronoun uses replaced with explicit nouns - [ ] Content maintains technical accuracy - [ ] Tone is conversational and helpful - [ ] Sentences are concise and scannable From 0b06c29f8abb24704151ca77e5d376cff60b53de Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Tue, 17 Mar 2026 14:37:29 -0700 Subject: [PATCH 8/8] Update Markdown writing style instructions Removed a guideline about using 'this' as a standalone pronoun. --- .github/instructions/Markdown.WritingStyle.instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/instructions/Markdown.WritingStyle.instructions.md b/.github/instructions/Markdown.WritingStyle.instructions.md index 045c291e0e7fa..39e71b578e3ca 100644 --- a/.github/instructions/Markdown.WritingStyle.instructions.md +++ b/.github/instructions/Markdown.WritingStyle.instructions.md @@ -21,6 +21,7 @@ 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 +- "this" as a standalone pronoun — replace it with the specific noun it refers to (adjectival use before a noun, such as "this method", is fine) ALWAYS: - Write like you speak using everyday words