Merge branch 'main' into gurardrex/blazor-split-routing-and-navigaton

Author: guardrex

.github/copilot-issue-verification-action-plan.md

@@ -0,0 +1,220 @@
+---
+ai-usage: ai-assisted
+author: tdykstra
+ms.author: wpickett
+ms.date: 11/13/2025
+---
+
+# GitHub issue analysis and action plan prompt for ASP.NET Core documentation
+
+## Goal
+Analyze the GitHub issue and provide a **structured report** determining:
+1. Whether the issue is valid and actionable.
+2. Whether the issue is within scope of the articles the issue relates to, or if a new article is needed.
+3. The exact documentation changes required (if applicable).
+4. A clear action plan that can guide PR creation.
+
+The report should be suitable for posting directly in the issue discussion.
+
+---
+
+## Analysis Steps
+
+### 1. Information Gathering
+Collect and review:
+* The **issue title, description, and all comments**.
+* The **published documentation** (via the provided URL).
+* The **source file(s)** in the repository.
+* Any **linked issues, PRs, or external references**.
+* **Environment details**: .NET version, tooling versions (VS, VS Code, CLI, EF Core, etc.).
+* **Code samples or error messages** mentioned in the issue.
+
+### 1.5 Source File Analysis
+When examining source files:
+* **Provide direct GitHub permalinks** to specific lines or sections.
+* **Note exact line numbers** for proposed changes.
+* **Include line number ranges** in GitHub URLs using `#L<start>-L<end>` format.
+* **Quote current content** from specific lines before proposing changes.
+* **Use permalinks with commit SHA** when referencing specific versions.
+
+Example format for file references:
+* Single line: `https://github.com/owner/repo/blob/main/file.md#L123`.
+* Line range: `https://github.com/owner/repo/blob/main/file.md#L123-L145`.
+* Permalink: `https://github.com/owner/repo/blob/<commit-sha>/file.md#L123`.
+
+### 2. Validation Criteria
+Determine if the issue is:
+* **In scope**: Related to ASP.NET Core documentation (not product bugs).
+* **Accurate**: The reported problem genuinely exists.
+* **Clear**: Sufficient information to take action.
+* **Current**: Applies to supported .NET versions.
+
+### 3. Translation Requirements
+If any content is not in English:
+* Include the original text in a quote block.
+* Provide complete English translation.
+* Label clearly as "Original" and "Translation".
+
+---
+
+## Output Format
+
+### File Naming
+`<issue-number>-analysis-report.md`
+
+### Report Structure
+
+#### Header
+```markdown
+## AI Analysis Report
+**Analyzed by:** @<github-username>
+**Date:** <YYYY-MM-DD>
+**Issue:** #<issue-number>
+**Model:** GitHub Copilot
+---
+```
+
+#### For Valid Issues
+
+```markdown
+# Issue Analysis: <Concise Issue Title>
+
+## ✅ Issue Validation
+**Status:** Valid and actionable
+
+## 📋 Issue Summary
+<Brief description of the problem and why it needs to be addressed>
+
+## 📁 Affected Files
+| File | Path | Lines | Section |
+|------|------|-------|---------|
+| Main article | [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) | 123-145 | "Section Heading" |
+| Code sample | [`aspnetcore/path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/sample.cs#L45-L67) | 45-67 | `MethodName()` method |
+
+## 📝 Proposed Changes
+
+### Documentation Updates
+**File:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145)
+**Location:** Lines 123-145 (after the paragraph containing "[specific anchor text]")
+**Type:** [New paragraph / Note block / Code example / Replacement]
+
+**Current content (lines 123-125):**
+```markdown
+[Current text that will be replaced or followed]
+```
+
+**Proposed change:**
+```markdown
+[Proposed documentation text here]
+```
+
+### Code Sample Updates (if applicable)
+**File:** [`sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67)
+**Lines:** 45-67
+**Change:** [Add/Modify/Remove]
+
+**Current code:**
+```csharp
+// Current code at specified lines
+```
+
+**Proposed code:**
+```csharp
+// Proposed code changes
+```
+
+## 🎯 Action Plan
+1. **Edit file:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md)
+   * Navigate to: [Line 123](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123)
+   * Find section: "Exact Section Heading"
+   * After text: "last sentence before insertion point"
+   * Insert: [!NOTE] block with explanation
+   
+2. **Update sample:** [`path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs)
+   * Navigate to: [Lines 45-67](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67)
+   * Modify method: `MethodName()`
+   * Change: Update to use new pattern
+
+## ⚠️ Considerations
+* Verify change applies to .NET [version]
+* Check if similar updates needed in related articles
+* Consider adding cross-references to [related topic]
+
+## 🔗 References
+* Published article: [URL]
+* Related issue: #[number]
+* Microsoft Learn docs: [relevant MS docs link]
+```
+
+#### For Invalid Issues
+
+```markdown
+# Issue Analysis: <Issue Title>
+
+## ❌ Issue Validation
+**Status:** Not actionable as is
+**Reason:** [Out of scope / Insufficient information / Product issue / Already addressed]
+
+## 📋 Explanation
+<Clear explanation of why the issue cannot be addressed as documentation>
+
+## 💡 Recommendation
+* [Close with explanation]
+* [Redirect to appropriate repository]
+* [Request additional information]
+* [Convert to discussion]
+
+## 🔗 Alternative Resources
+* [Link to relevant documentation]
+* [Link to appropriate repository for product issues]
+```
+
+---
+
+## Special Instructions
+
+### Line Number Guidelines
+* **Always inspect the actual source file** to determine accurate line numbers.
+* **Provide line ranges** rather than single lines when changes affect multiple lines.
+* **Use GitHub's line highlighting** format in URLs (#L123 for single, #L123-L145 for range).
+* **Quote the existing content** at those lines to confirm accuracy.
+* **Consider context lines** - include a few lines before/after for clarity.
+* **Update line numbers** if the file has changed since issue creation.
+
+### Content Block Usage
+Only recommend using special blocks when truly appropriate, they should not be overused:
+* `[!IMPORTANT]`: Security issues, breaking changes, data loss risks
+* `[!WARNING]`: Common mistakes, deprecation notices
+* `[!NOTE]`: Helpful clarifications, version-specific info
+* `[!TIP]`: Best practices, productivity hints
+
+### Code Samples
+* Use appropriate language identifier for syntax highlighting.
+* Include necessary `using` statements or imports.
+* Add comments for complex logic.
+* Ensure samples are complete and runnable.
+
+### Scope Boundaries
+**DO:**
+* Focus on documentation clarity and accuracy.
+* Address missing information.
+* Fix technical inaccuracies.
+* Improve code samples.
+
+**DON'T:**
+* Attempt to fix product bugs through documentation.
+* Make architectural recommendations.
+* Add opinions or preferences.
+* Modify unrelated sections.
+
+## Issue labels
+* Upon completion of the report, set the `ai-reviewed-issue-reported-action-plan` label for the issue.
+
+### Common Issue Types
+1. **Missing information**: Add clarifying content
+2. **Outdated content**: Update to current version
+3. **Broken samples**: Fix or replace code
+4. **Unclear instructions**: Rewrite for clarity
+5. **Missing prerequisites**: Add setup steps
+
+---

.github/workflows/blazor-issue-processing.yml

@@ -25,7 +25,19 @@ jobs:
               repo: context.repo.repo,
               body: `### 🦃 ***Happy Thanksgiving!*** 🍽️
 
-            *Stand-by!* A green dinosaur 🦖 will be along shortly to assist.`
+            This issue has been marked for triage on the Blazor Docs GitHub project, and I'll respond after the Thanksgiving holiday during the first week of December.
+
+            We only work on documentation on this repo. If you need product support, close this issue and seek assistance through one or more of the following support channels:
+
+            * [Stack Overflow (tagged: 'blazor')](https://stackoverflow.com/questions/tagged/blazor)
+            * [General ASP.NET Core Slack Team](https://aspnetcore.slack.com/join/shared_invite/zt-1mv5487zb-EOZxJ1iqb0A0ajowEbxByQ#/shared-invite/email)
+            * [Blazor Gitter](https://gitter.im/aspnet/Blazor)
+
+            If you think that you found a potential bug in the framework or have product feedback, close this issue and open a new issue for the ASP.NET Core product unit at [dotnet/aspnetcore issues](https://github.com/dotnet/aspnetcore/issues). Bug reports require a clear explanation of the problem, usually including a minimal repro project placed on GitHub for the product unit engineers to download and run. If you determine with the product unit that it isn't a bug but merely requires documentation, please re-open this docs issue and place a cross-link to your engineering issue discussion.
+
+            For problems or feedback on Visual Studio, close this issue and use the [**Report a Problem**](https://docs.microsoft.com/visualstudio/ide/how-to-report-a-problem-with-visual-studio) or [**Suggest a Feature**](https://docs.microsoft.com/visualstudio/ide/suggest-a-feature) processes from within VS, which open internal issues for the VS product unit. For more information, see [Visual Studio Feedback](https://developercommunity.visualstudio.com/home).
+
+            For problems with Visual Studio Code, close this issue and ask for support on community support forums. For bug reports and product feedback, open an issue on the [microsoft/vscode GitHub repo](https://github.com/microsoft/vscode/issues).`
             })
             await github.rest.issues.addLabels({
               issue_number: context.issue.number,

.github/workflows/quest-bulk.yml

@@ -27,7 +27,9 @@ jobs:
       - name: "Print manual bulk import run reason"
         if: ${{ github.event_name == 'workflow_dispatch' }}
         run: |
-          echo "Reason: ${{ github.event.inputs.reason }}"
+          echo "Reason: $REASON"
+        env:
+          REASON: ${{ github.event.inputs.reason }}
 
       - name: Azure OpenID Connect
         id: azure-oidc-auth

.github/workflows/quest.yml

@@ -28,8 +28,11 @@ jobs:
       - name: "Print manual run reason"
         if: ${{ github.event_name == 'workflow_dispatch' }}
         run: |
-          echo "Reason: ${{ github.event.inputs.reason }}"
-          echo "Issue number: ${{ github.event.inputs.issue }}"
+          echo "Reason: $REASON"
+          echo "Issue number: $ISSUENUMBER"
+        env:
+          REASON: ${{ github.event.inputs.reason }}
+          ISSUENUMBER: ${{ github.event.inputs.issue }}
 
       - name: Azure OpenID Connect
         id: azure-oidc-auth