diff --git a/.github/instructions/ado-work-items-markdown.instructions.md b/.github/instructions/ado-work-items-markdown.instructions.md new file mode 100644 index 0000000000..2a70fd124a --- /dev/null +++ b/.github/instructions/ado-work-items-markdown.instructions.md @@ -0,0 +1,139 @@ +--- +applyTo: "**" +--- +# Azure DevOps Work Items: Markdown Description Rules + +Use this guide whenever creating or updating Azure DevOps work items that include rich text in `System.Description`. + +## Goals + +- Ensure descriptions render as Markdown (not HTML/plain text) +- Preserve newline characters and list structure +- Verify work items after every batch update + +## Required Behavior + +1. Always use `az rest` for description content-type changes. +2. Use `application/json-patch+json` for PATCH requests. +3. Set `multilineFieldsFormat.System.Description` to `markdown`. +4. Preserve exact newlines in the Markdown body. +5. Verify both format and newline integrity after updates. + +## Authentication and Resource + +Use Azure DevOps resource audience when calling `az rest`: + +- Resource: `499b84ac-1321-427f-aa17-267ca6975798` + +Example auth check: + +```bash +az rest \ + --method GET \ + --resource 499b84ac-1321-427f-aa17-267ca6975798 \ + --url "https://dev.azure.com//_apis/projects?api-version=7.1-preview.4" +``` + +Note: API versions can differ by endpoint. The examples below use `7.1-preview.3` for work item PATCH calls, while this auth check uses `7.1-preview.4`. + +## Safe Update Pattern (Prevents Type/Value Errors) + +Some work items reject a direct type switch unless a valid value is provided. Use this two-step process: + +### Step 1: Capture current description + +```bash +az boards work-item show --id | jq -j '.fields["System.Description"] // ""' > ./desc-backup.txt +``` + +> **NOTE**: Writing to a file preserves all characters including trailing newlines. +> Command substitution (`$(...)`) silently strips trailing newlines, which would +> corrupt multi-line Markdown content. + +### Step 2: Force markdown type with temporary empty value + +```bash +PATCH_STEP1_FILE="${PATCH_STEP1_FILE:-./patch-step1.json}" + +jq -n '[ + {"op":"replace","path":"/fields/System.Description","value":""}, + {"op":"replace","path":"/multilineFieldsFormat/System.Description","value":"markdown"} +]' >"$PATCH_STEP1_FILE" + +az rest \ + --method PATCH \ + --resource 499b84ac-1321-427f-aa17-267ca6975798 \ + --url "https://dev.azure.com///_apis/wit/workitems/?api-version=7.1-preview.3" \ + --headers "Content-Type=application/json-patch+json" \ + --body @"$PATCH_STEP1_FILE" +``` + +### Step 3: Restore exact Markdown text + +```bash +PATCH_STEP2_FILE="${PATCH_STEP2_FILE:-./patch-step2.json}" + +jq -n --rawfile d ./desc-backup.txt '[ + {"op":"replace","path":"/fields/System.Description","value":$d} +]' >"$PATCH_STEP2_FILE" + +az rest \ + --method PATCH \ + --resource 499b84ac-1321-427f-aa17-267ca6975798 \ + --url "https://dev.azure.com///_apis/wit/workitems/?api-version=7.1-preview.3" \ + --headers "Content-Type=application/json-patch+json" \ + --body @"$PATCH_STEP2_FILE" +``` + +## Newline Integrity Checks + +After updates, confirm newline characters are still present and structure was not flattened. + +### Check format and description sample + +```bash +az boards work-item show --id | jq '.multilineFieldsFormat, .fields["System.Description"][0:200]' +``` + +Expected: + +- `multilineFieldsFormat.System.Description == "markdown"` +- Description text contains `\n` where line breaks are expected + +### Check line count did not collapse + +```bash +az boards work-item show --id \ +| jq -r '.fields["System.Description"]' \ +| awk 'END { print NR }' +``` + +If a multi-line description unexpectedly returns `1`, newline content was likely lost. + +## Batch Verification Script + +Use this after bulk updates: + +```bash +python3 - <<'PY' +import json, subprocess +ids = [12345, 12346] # replace with your target IDs +bad = [] +for i in ids: + out = subprocess.check_output(["az", "boards", "work-item", "show", "--id", str(i)], text=True) + j = json.loads(out) + fmt = (j.get("multilineFieldsFormat") or {}).get("System.Description") + desc = j.get("fields", {}).get("System.Description") or "" + if fmt != "markdown" or "\n" not in desc: + bad.append((i, fmt, "has_newlines" if "\n" in desc else "missing_newlines")) +print("noncompliant:", len(bad)) +for row in bad: + print(row) +PY +``` + +## Common Failure Modes + +- `401` or `TF400813`: wrong token audience or insufficient auth context +- `Content-Type ... not supported`: must use `application/json-patch+json` +- `type changed without a value`: use two-step pattern (empty + markdown type, then restore text) diff --git a/.github/prompts/review-pr-feedback.prompt.md b/.github/prompts/review-pr-feedback.prompt.md new file mode 100644 index 0000000000..c14a7b96cb --- /dev/null +++ b/.github/prompts/review-pr-feedback.prompt.md @@ -0,0 +1,123 @@ +--- +name: review-pr-feedback +description: Uses gh CLI to collect unresolved PR review feedback, optionally includes discussion comments, applies fixes, and reports status. +argument-hint: pr= repo= includeDiscussionComments= authorFilter= testScope= +tools: ['edit/editFiles', 'edit/createFile', 'read/readFile', 'read/problems', 'search/codebase', 'search/textSearch', 'search/fileSearch', 'execute/runInTerminal', 'execute/getTerminalOutput'] +--- +You are an expert software maintenance agent focused on resolving pull request feedback quickly, safely, and with clear traceability. + +## Context +- Workspace root: ${workspaceFolder} +- Target PR: ${input:pr} +- Optional repository override: ${input:repo} +- Include non-review discussion comments: ${input:includeDiscussionComments} +- Optional author filter: ${input:authorFilter} +- Optional focused testing hint: ${input:testScope} +- Optional selected context: ${selection} + +## Skills +#skill:generate-mstest-filter + +Use this skill when building a dotnet test filter: +- [generate-mstest-filter](.github/skills/generate-mstest-filter/SKILL.md) + +Follow the referenced skill instructions before producing any custom filter. + +## Task +1. Validate prerequisites +- Confirm gh CLI is installed and authenticated. +- Resolve repository from ${input:repo}, or infer from git remote. +- Resolve PR number from ${input:pr} (accept number or URL). +- Discover the correct git remote name from the current repository and store it for later commands. +- Use that discovered remote name for push and any other git operations that require a remote; do not assume `origin`. + +2. Gather actionable review feedback +- Query PR review threads with gh api GraphQL. +- Keep only unresolved threads where isResolved is false. +- Extract thread id, file path, line/startLine, comment url, author login, and body. +- If ${input:authorFilter} is provided, apply it case-insensitively. + +3. Optionally gather non-review discussion comments +- If ${input:includeDiscussionComments} is true, fetch PR issue comments. +- Mark these as Informational because they do not have open/resolved state. +- Apply ${input:authorFilter} if provided. + +4. Build an implementation plan +- Group unresolved review feedback by file and risk. +- Determine minimal safe edits needed. +- Identify comments that are non-actionable or ambiguous. +- Ask the user to confirm the plan before proceeding, showing a concise summary of proposed changes and rationale. + +5. Implement and verify +- Apply required code or test updates with smallest safe change set. +- Run targeted checks first. +- If ${input:testScope} is provided, generate and use a focused MSTest filter via the skill. +- Collect diagnostics when tests cannot run. + +6. Classify each item +- Fixed: change implemented and validated. +- Needs Clarification: ambiguous, conflicting, or insufficiently specified. +- Blocked: external dependency, permission, or missing context. +- Informational: non-review discussion comment captured only. + +7. Produce a final report +- Keep review-thread outcomes and discussion outcomes in separate sections. +- Include evidence for each item: file location, change summary, validation result. +- Draft a distinct reply for each comment item that addresses that exact comment's request, context, and outcome. + +8. Commit changes +- If any changes were made, create a commit with a clear message referencing the PR and summarizing the resolution. +- Prompt the user to review and confirm the commit message before finalizing. +- When suggesting or performing a push, use the discovered git remote name. +- Prompt the user to push the commit if they have permissions, or provide instructions if they do not. +- Prompt the user to reply to each original PR comment with a comment-specific response and link to the relevant commit or code location, if appropriate. +- Prompt the user to mark review threads as resolved in GitHub if they have permissions, or provide instructions if they do not. + +## Output Format +1. PR Scope +- Repo +- PR number +- Unresolved review threads found +- Discussion comments found (if enabled) + +2. Unresolved Review Feedback (Actionable) +- Item: +- Location: : +- Author: +- Request summary: +- Action taken: +- Status: Fixed | Needs Clarification | Blocked +- Evidence: +- Suggested reply: + +3. Discussion Comments (Informational, optional) +- Item: +- Author: +- Summary: +- Notes: +- Suggested reply: + +4. Validation +- Commands run +- Filters used +- Pass/fail summary +- Remaining warnings/errors + +5. Final Summary +- Files changed +- Number fixed +- Number needing clarification +- Number blocked +- Number informational +- Recommended next step + +## Rules +- Do not invent comments; only act on data fetched from gh. +- Review-thread resolution tracking is authoritative for unresolved state. +- Keep behavior-compatible edits unless feedback explicitly requires change. +- If no unresolved review threads exist, report that explicitly. +- If auth or permission fails, report exact failure and minimum required user action. +- Do not use `set -e` in bash commands or scripts. +- After each terminal step, verify the bash session is still alive; if it died, report it immediately, start a new session, and continue from the last confirmed checkpoint. +- Use the discovered git remote name consistently anywhere a remote is required. +- Do not post generic batch replies; each reply must be tailored to the specific comment content and its exact resolution status. diff --git a/AGENTS.md b/AGENTS.md index 06bc0edfd1..c461eec189 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ This document provides guidance for AI coding agents working with the Microsoft. ## Quick Start ### Essential Context Files + Before making changes, agents should be aware of: | File | Purpose | @@ -15,6 +16,7 @@ Before making changes, agents should be aware of: | [.github/copilot-instructions.md](.github/copilot-instructions.md) | Copilot-specific instructions | ### Detailed Technical Instructions + The `.github/instructions/` directory contains comprehensive guides: | Guide | Coverage | @@ -29,6 +31,7 @@ The `.github/instructions/` directory contains comprehensive guides: | [features.instructions.md](.github/instructions/features.instructions.md) | Feature reference, keywords | | [documentation.instructions.md](.github/instructions/documentation.instructions.md) | Documentation and samples | | [external-resources.instructions.md](.github/instructions/external-resources.instructions.md) | Docs links, version matrix, external references | +| [ado-work-items-markdown.instructions.md](.github/instructions/ado-work-items-markdown.instructions.md) | Ensure Azure DevOps work item descriptions are Markdown and preserve newlines | ## Workflow Prompts @@ -77,6 +80,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level ## Common Tasks ### Bug Fix Workflow + 1. Understand the issue from the bug report 2. Locate relevant code in `src/Microsoft.Data.SqlClient/src/` (do NOT modify legacy `netcore/src/` or `netfx/src/`) 3. Check `.github/instructions/features.instructions.md` for existing AppContext switches (including failover compatibility switches) before introducing behavior changes @@ -86,6 +90,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level 7. Update documentation if behavior changes ### Feature Implementation + 1. Review the feature specification 2. Plan the implementation (see `implement-feature` prompt) 3. Update reference assemblies if adding public APIs @@ -94,6 +99,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level 6. Do not edit `CHANGELOG.md` directly; instead, add a suggested release-note entry (per `.github/copilot-instructions.md`) in the PR description or via the release-notes workflow/prompt. ### Adding Connection String Keywords + 1. Add to `SqlConnectionStringBuilder` 2. Update connection string parser 3. Default to backward-compatible value @@ -101,6 +107,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level 5. Document in feature reference ### Protocol Changes + 1. Reference MS-TDS specification 2. Update `TdsEnums.cs` for new constants 3. Implement in `TdsParser.cs` and related files @@ -108,6 +115,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level 5. Consider backward compatibility ### Performance Optimization + 1. Profile the issue using benchmarks or traces 2. Identify allocation hotspots (see `perf-optimization` prompt) 3. Apply patterns: `ArrayPool`, `Span`, static/cached instances, source generation @@ -117,6 +125,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level ### Key Documentation Links + - [Microsoft.Data.SqlClient on Microsoft Learn](https://learn.microsoft.com/sql/connect/ado-net/introduction-microsoft-data-sqlclient-namespace) - [MS-TDS Protocol Specification](https://learn.microsoft.com/openspecs/windows_protocols/ms-tds) - [SQL Server Documentation](https://learn.microsoft.com/sql/sql-server/) @@ -124,6 +133,7 @@ Do **not** create branches directly under `main`, `dev/`, or any other top-level ## Repository Policies See the `policy/` directory for: + - [coding-best-practices.md](policy/coding-best-practices.md) - Programming standards - [coding-style.md](policy/coding-style.md) - Code formatting guidelines - [review-process.md](policy/review-process.md) - PR review requirements