From 419bb103242c29b04a2106da2efe2eb30b8e5f12 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 10 Oct 2026 11:17:59 +0200 Subject: [PATCH] Answer product-owner round 1: the migration row names the trigger and how to keep one list, the changelog groups the list entries and labels its fixes, and the README's second group says it has other reasons --- CHANGELOG.md | 22 +++++++++++----------- MIGRATION.md | 2 +- README.md | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8873feb..301010f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ CommonMark reads it: `- a` then `* b`, `1. a` then `1) b`. `adfToLosslessMarkdown` gives a list right after one of its kind the other marker, `* ` or `1)`, in place of the `::listBreak` separator. Convert stored markdown per `MIGRATION.md`. +- **Breaking:** a link reference definition between two list items ends the list, as CommonMark + reads it: `- a`, `[r]: /u`, `- b` read as two lists, where `0.1.0` read one; see `MIGRATION.md`. - **Breaking:** each call names the markdown it reads or writes. `adfToMarkdown` and `markdownToAdf` are now `adfToLosslessMarkdown` and `losslessMarkdownToAdf`. A bot's or a model's markdown reads in `portableMarkdownToAdf`, and markdown known to be strict CommonMark in the new @@ -56,17 +58,15 @@ `losslessMarkdownToAdf` refuses a directive mark wrapping only hard breaks as `unsupported-node-shape`. `adfToLosslessMarkdown` writes a hard break holding marks as `!adf:carry{json="…"}`. See `MIGRATION.md`. -- **Breaking:** two lists a link reference definition parts read as two lists, as CommonMark - reads them, where `0.1.0` read one; see `MIGRATION.md`. -- `adfToLosslessMarkdown` and `adfToPortableMarkdown` write text holding a long run of `*`, `_`, `~` - or backticks, or a heading ending in a long run of `#`, in time linear in the run: a run of 20000 - `*` took seconds before, and now takes milliseconds. -- `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as `JSON.parse` builds it: - two adjacent text nodes CommonMark would read back as one are parted by `!adf:textBreak{}`, an - empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`, `{content=empty}` or - `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text nodes is a fence per - node. A `codeBlock` holding other than plain text nodes rides the block carry, where it was - refused. +- Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of + `*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: it is linear in the run, and + a run of 20000 `*` takes milliseconds where it took seconds. +- Fix the round-trip: `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as + `JSON.parse` builds it: two adjacent text nodes CommonMark would read back as one are parted by + `!adf:textBreak{}`, an empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`, + `{content=empty}` or `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text + nodes is a fence per node. A `codeBlock` holding other than plain text nodes rides the block + carry, where it was refused. - Fix a link `title` holding a null character: it is written as `!adf:link[text]{attrs}`, where it read back as U+FFFD. - Fix an image inside another image's description: it flattens into the alt text, where it was diff --git a/MIGRATION.md b/MIGRATION.md index 5fde8a1..0914d4c 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -77,7 +77,7 @@ Markdown the spelling table leaves alone, which `0.2.0` reads as a different doc | Input | `0.1.0` | `0.2.0` | | --- | --- | --- | | a list whose bullet character or ordered delimiter changes (`- a` then `* b`, `1. a` then `1) b`) | one list | two lists, as CommonMark reads them | -| two lists a link reference definition parts (`- a`, `[r]: /u`, `- b`, a blank line between each) | one list | two lists, as CommonMark reads them | +| a link reference definition between two list items, at the list's own indentation (`- a`, a blank line, `[r]: /u`, `- b`) | one list | two lists, as CommonMark reads them; indent the definition under the item, or move it below the list, to keep one list | | a link whose text already holds one (`[ab](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text; write the pieces as separate links to keep them | | markdown holding no block (`""`) | `{ type: 'doc', version: 1 }` | `{ content: [], type: 'doc', version: 1 }`; `!adf:doc {content=none}` reads as the former | | a hard break inside a mark's spelling (`*a\` then `b*` on the next line) | the hard break holds the mark | the hard break holds no marks, as Atlassian's schema requires, and the recipe above drops the marks `0.1.0` gave it wherever text beside it holds them. A link whose text is only hard breaks reads as its destination linked, followed by those breaks | diff --git a/README.md b/README.md index a847a8b..850c255 100644 --- a/README.md +++ b/README.md @@ -253,7 +253,7 @@ Serves Goals 1, 4 and 5. - An image's title becomes its caption when the image stays an image, and its link's title when it becomes linked alt text. Inside another link, the title is dropped. - And these: a shortcut reference matching its definition only under Unicode case folding stays + And these, for other reasons: a shortcut reference matching its definition only under Unicode case folding stays unresolved, and a link whose text holds an autolink keeps the inner link and leaves the outer brackets literal text, which the spec requires and the reference itself breaks, nesting one `` in the other. `corpus/commonmark-spec/exceptions.json` pins the spellings ADF holds no node for