docs: Add Azure DevOps work item markdown formatting guide#4253
Open
paulmedynski wants to merge 1 commit intomainfrom
Open
docs: Add Azure DevOps work item markdown formatting guide#4253paulmedynski wants to merge 1 commit intomainfrom
paulmedynski wants to merge 1 commit intomainfrom
Conversation
- Create ado-work-items-markdown.instructions.md with safe patterns for markdown description updates - Document two-step conversion for changing field format without data loss - Include newline integrity checks and batch verification scripts - Update AGENTS.md to link new instruction guide for discoverability
paulmedynski
added
the
Area\Engineering
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new repository instruction guide documenting a safe, repeatable workflow for updating Azure DevOps work item descriptions to Markdown while preserving newline integrity, and links it from the agent guidance index.
Changes:
- Added a new instruction file under
.github/instructions/coveringaz restJSON-patch patterns and verification scripts forSystem.DescriptionMarkdown formatting. - Updated
AGENTS.mdto reference the new guide in the “Detailed Technical Instructions” table. - Minor formatting tweaks in
AGENTS.md(additional blank lines for readability).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
.github/instructions/ado-work-items-markdown.instructions.md |
New guide documenting Markdown formatting rules, safe update steps, and post-update verification checks for ADO work items. |
AGENTS.md |
Adds a link to the new ADO work item Markdown guide in the technical instructions table (plus minor spacing adjustments). |
Comment on lines
+49
to
+60
| ```bash | ||
| jq -n '[ | ||
| {"op":"replace","path":"/fields/System.Description","value":""}, | ||
| {"op":"replace","path":"/multilineFieldsFormat/System.Description","value":"markdown"} | ||
| ]' >/tmp/patch-step1.json | ||
|
|
||
| az rest \ | ||
| --method PATCH \ | ||
| --resource 499b84ac-1321-427f-aa17-267ca6975798 \ | ||
| --url "https://dev.azure.com/<org>/<project>/_apis/wit/workitems/<id>?api-version=7.1-preview.3" \ | ||
| --headers "Content-Type=application/json-patch+json" \ | ||
| --body @/tmp/patch-step1.json |
| ```bash | ||
| python3 - <<'PY' | ||
| import json, subprocess | ||
| ids = [44787, 44794] # replace with your target IDs |
| az rest \ | ||
| --method GET \ | ||
| --resource 499b84ac-1321-427f-aa17-267ca6975798 \ | ||
| --url "https://dev.azure.com/<org>/_apis/projects?api-version=7.1-preview.4" |
Comment on lines
+66
to
+75
| jq -n --arg d "$desc" '[ | ||
| {"op":"replace","path":"/fields/System.Description","value":$d} | ||
| ]' >/tmp/patch-step2.json | ||
|
|
||
| az rest \ | ||
| --method PATCH \ | ||
| --resource 499b84ac-1321-427f-aa17-267ca6975798 \ | ||
| --url "https://dev.azure.com/<org>/<project>/_apis/wit/workitems/<id>?api-version=7.1-preview.3" \ | ||
| --headers "Content-Type=application/json-patch+json" \ | ||
| --body @/tmp/patch-step2.json |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds comprehensive instructions for ensuring markdown content is properly formatted when creating or updating Azure DevOps work items.
Changes
New file:
.github/instructions/ado-work-items-markdown.instructions.mdUpdated:
AGENTS.mdContext
These instructions document the workflow discovered while updating 26 work items (4 stories + 22 tasks) for the pipeline implementation project. The patterns ensure: