From c690a12ff63b8c2298b1ecdcabb768b0e8d9c193 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 21 Nov 2025 12:02:37 -0500 Subject: [PATCH 1/3] Incorporate new recommendations See discussion on #49119 --- .github/copilot-instructions.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7c3fa1b632662..a925f43abdd73 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -58,6 +58,32 @@ Examples: - ❌ Bad: `configure_logging.md` - ❌ Bad: `DependencyInjectionGuidelines.md` +## Documentation from External Sources (Blog Posts, Announcements) + +When adapting content from external sources like blog posts into documentation: + +**DO:** +- Work on one version/topic at a time - never combine multiple versions in a single PR. +- Copy working code samples directly from source when available. +- Execute and validate all code examples with appropriate tools (`dotnet fsi` for F#, simple console apps for C#). +- Provide execution proofs in PR comments for any generated code. +- Create a checklist TODO for each section of the source document before writing. +- Map each documentation section 1:1 to source content. +- Explicitly state what is copied vs. generated in PR description. + +**DON'T:** +- Invent or elaborate on features not explicitly mentioned in source. +- Create placeholder sections without content. +- Assume feature details or characteristics. +- Combine information from multiple versions/sources. +- Add examples without verifying they demonstrate the stated feature. + +**PR Description Must Include:** +- Content source breakdown (% copied vs. generated). +- List of fabricated/generated sections requiring expert review. +- Execution proof for all code samples. +- Clear warnings about any uncertainties. + ## Special Cases ### Breaking Changes From e46e104fb0580d52a86947da1ff23c283e62893e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 21 Nov 2025 13:58:08 -0500 Subject: [PATCH 2/3] holistically respond to feedback I didn't take any of the suggestions as noted, but made edits consistent will all recommendations. --- .github/copilot-instructions.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a925f43abdd73..b71f07a616543 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -64,12 +64,11 @@ When adapting content from external sources like blog posts into documentation: **DO:** - Work on one version/topic at a time - never combine multiple versions in a single PR. -- Copy working code samples directly from source when available. -- Execute and validate all code examples with appropriate tools (`dotnet fsi` for F#, simple console apps for C#). -- Provide execution proofs in PR comments for any generated code. +- Copy working code samples directly from source when available. Follow the rules under ["Code Snippets"](#code-snippets) above. - Create a checklist TODO for each section of the source document before writing. - Map each documentation section 1:1 to source content. - Explicitly state what is copied vs. generated in PR description. +- Add disclaimers about AI usage when applicable. **DON'T:** - Invent or elaborate on features not explicitly mentioned in source. @@ -79,9 +78,8 @@ When adapting content from external sources like blog posts into documentation: - Add examples without verifying they demonstrate the stated feature. **PR Description Must Include:** -- Content source breakdown (% copied vs. generated). -- List of fabricated/generated sections requiring expert review. -- Execution proof for all code samples. +- Content source breakdown. In the description, list each section of the source document and indicate whether it was copied verbatim, adapted, or newly generated. +- Note all generated sections requiring expert review. - Clear warnings about any uncertainties. ## Special Cases From 958cc491e32c3086c6a0aa9efdf2a3ffe6c1f8be Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 21 Nov 2025 14:09:18 -0500 Subject: [PATCH 3/3] 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 b71f07a616543..4f6ad99f24ff1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -63,7 +63,7 @@ Examples: When adapting content from external sources like blog posts into documentation: **DO:** -- Work on one version/topic at a time - never combine multiple versions in a single PR. +- Work on one version, or topic at a time - never combine multiple versions in a single PR. Some blog posts or source material may include many versions or preview builds. The issue or task should specify which one to focus on. - Copy working code samples directly from source when available. Follow the rules under ["Code Snippets"](#code-snippets) above. - Create a checklist TODO for each section of the source document before writing. - Map each documentation section 1:1 to source content.