DOCS-1872 - Clarify when Jira descriptions need ADF instead of markdown - #7111
Merged
Merged
Conversation
The Jira field rules said to always use contentFormat: markdown for descriptions. Markdown is a lossy conversion layer over ADF, which is what Jira Cloud actually stores, so rewriting a description as markdown silently deletes any node markdown cannot express: media, panels, expand blocks, status lozenges, mentions, dates, and layouts. Rewriting DOCS-1867 hit this. Its description embedded two screenshots that a markdown write would have dropped, and on read they surfaced only as blob: placeholder URLs that are not usable image sources. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
Folded into #7099 (DOCS-1867) instead. Same one-line change, byte-identical, now carried by a ticketed PR rather than standing alone without one. The two are more connected than a separate PR suggested: the ADF problem surfaced while rewriting the DOCS-1867 ticket description, whose two screenshots a markdown write would have silently dropped. Branch |
Collaborator
Author
|
Reopening. The ADF rule is out of scope for #7099, which is specifically about GitHub PR comments and Jira ticket comments, so it belongs here on its own after all. |
kimsauce
changed the title
mafsumo
approved these changes
Sep 10, 2026
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
2 participants
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.
Purpose of this pull request
Corrects the Jira Description field rule in
AGENTS.md, which said to always usecontentFormat: markdown. That silently deletes content on any ticket holding more than plain text.Jira Cloud stores rich text as ADF. Markdown is a lossy conversion layer on top of it, so writing a description as markdown drops anything markdown cannot express: attached images and other media, panels, expand and collapse blocks, status lozenges,
@mentions, date nodes, and column layouts. Reading is lossy in the same direction. A media node comes back as ablob:placeholder rather than a usable image source, so writing it back destroys the attachment.The revised rule keeps markdown as the default for text-only fields, switches to ADF when the field holds anything richer, and says to fetch a field as ADF first when you are unsure what it contains.
Select the type of change
Ticket (if applicable)
https://sumologic.atlassian.net/browse/DOCS-1872
🤖 Generated with Claude Code