mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +01:00
Answer stability round 1: 0 🔴, 2 🟡 (0 misread); read foreign HTML best effort, never refused, and scope the htmlToAdf decision to item 137 with the dialect read first
This commit is contained in:
@@ -21,7 +21,7 @@ In `docs/decisions.md`:
|
|||||||
- Unknown nodes ride the carry
|
- Unknown nodes ride the carry
|
||||||
- The carry fence names the node type
|
- The carry fence names the node type
|
||||||
- A code block is a fence per text node
|
- A code block is a fence per text node
|
||||||
- Foreign HTML sorts three ways
|
- Foreign HTML reads best effort and is never refused
|
||||||
- Names stay text
|
- Names stay text
|
||||||
- Directives under `!adf:`
|
- Directives under `!adf:`
|
||||||
- CommonMark is a subset
|
- CommonMark is a subset
|
||||||
@@ -94,7 +94,7 @@ In `docs/decisions.md`:
|
|||||||
- The real-world corpus holds anonymized documents from sites whose licence it records
|
- The real-world corpus holds anonymized documents from sites whose licence it records
|
||||||
- The feature table is a section per corpus example, led by a summary table
|
- The feature table is a section per corpus example, led by a summary table
|
||||||
- Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented
|
- Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented
|
||||||
- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead
|
- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content
|
||||||
- `htmlToAdf` reads any HTML, with no option and no second call
|
- `htmlToAdf` reads any HTML, with no option and no second call
|
||||||
|
|
||||||
## 1. Nothing about any consumer in the library
|
## 1. Nothing about any consumer in the library
|
||||||
|
|||||||
@@ -286,9 +286,9 @@ which is free text.
|
|||||||
- **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back.
|
- **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back.
|
||||||
Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit.
|
Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit.
|
||||||
|
|
||||||
Behind those apps, the people who read and write the markdown and the HTML: product
|
Behind those apps, the people who read and write the markdown, the HTML and the Jira wiki markup:
|
||||||
managers, engineers and support agents working in Atlassian products through a plugin or another
|
product managers, engineers and support agents working in Atlassian products through a plugin or
|
||||||
UI. They know markdown and not ADF, and rely on every spelling saying what it means to them.
|
another UI. They know markdown and not ADF, and rely on every spelling saying what it means to them.
|
||||||
|
|
||||||
Also behind them, the people who read a document's plain text as they read an email, whether it
|
Also behind them, the people who read a document's plain text as they read an email, whether it
|
||||||
arrives in an email, a notification or a search hit. They see no markup, and rely on text that
|
arrives in an email, a notification or a search hit. They see no markup, and rely on text that
|
||||||
|
|||||||
+26
-22
@@ -161,25 +161,23 @@ node, so each node keeps its own text. The fences carry one info string, since A
|
|||||||
language, and none is empty beside another, since a text node holds text. The grammar:
|
language, and none is empty beside another, since a text node holds text. The grammar:
|
||||||
`spec/flavour.md` §The CommonMark blocks, the `codeBlock` bullet.
|
`spec/flavour.md` §The CommonMark blocks, the `codeBlock` bullet.
|
||||||
|
|
||||||
## Foreign HTML sorts three ways
|
## Foreign HTML reads best effort and is never refused
|
||||||
|
|
||||||
2026-08-23, the sort 2026-09-20, the maintainer. Goals 1 and 5. Valid while ADF holds no node
|
2026-08-23, the sort 2026-09-20, best effort 2026-11-15, the maintainer. Goals 7 and 12. Valid while
|
||||||
for a bare container, a comment or a script. Lands with `todo.md` item 137.
|
ADF holds no node for a bare container, a comment or a script. Lands with `todo.md` item 137.
|
||||||
|
|
||||||
Every foreign element `htmlToAdf` and the markdown readers read sorts one of three ways, never a
|
HTML from emails, CMSs and editors guarantees nothing, so no foreign element is refused. Each reads
|
||||||
silent drop of content:
|
one of two ways:
|
||||||
|
|
||||||
- A container around document content that ADF has no node for unwraps to its children, its own
|
- A container around document content that ADF has no node for unwraps to its children, its own
|
||||||
attributes dropped: `<div align="center">text</div>` keeps `text`, losing the alignment.
|
attributes dropped: `<div align="center">text</div>` keeps `text`, losing the alignment.
|
||||||
- Content ADF cannot hold is an error result naming it. A comment is one: a person wrote those
|
- What no reader sees drops whole: `<script>` and `<style>` with their text, and a comment, since a
|
||||||
words, and neither of Atlassian's schemas holds them — `annotation`'s `inlineComment` carries an
|
browser shows none of it and an email's conditional comments are markup.
|
||||||
id, `placeholder` is the editor's own hint, `extension` names a vendor app.
|
|
||||||
- What is not document content drops whole: `<script>` and `<style>`, their text with them.
|
|
||||||
|
|
||||||
`<details><summary>Title</summary>…</details>` is an `expand` titled by its summary, a
|
`<details><summary>Title</summary>…</details>` is an `expand` titled by its summary, a
|
||||||
`nestedExpand` inside another; an empty one is refused, since `expand` requires content. A `style`
|
`nestedExpand` inside another; an empty one holds an empty paragraph, since `expand` requires
|
||||||
attribute is not read at `0.4.0`: the `textColor` and `backgroundColor` it could reach cost more
|
content. A `style` attribute is not read at `0.4.0`: the `textColor` and `backgroundColor` it could
|
||||||
than they buy.
|
reach cost more than they buy.
|
||||||
The three markdown readers share one parser, so they take the same set.
|
The three markdown readers share one parser, so they take the same set.
|
||||||
|
|
||||||
## Names stay text
|
## Names stay text
|
||||||
@@ -1448,22 +1446,28 @@ alt text.
|
|||||||
extension or a synced block holding no text adds no note in its place.
|
extension or a synced block holding no text adds no note in its place.
|
||||||
- An expand's title on a line, a blank line above its body.
|
- An expand's title on a line, a blank line above its body.
|
||||||
|
|
||||||
## Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead
|
## Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content
|
||||||
|
|
||||||
2026-11-15, the maintainer. Goals 1, 7 and 11. Valid while Jira's renderer reads the `{adf}` macro.
|
2026-11-15, the maintainer. Goals 1, 7 and 11. Valid while Jira's renderer reads the `{adf}` macro.
|
||||||
Lands with `todo.md` items 192 to 196.
|
Lands with `todo.md` items 192 to 196.
|
||||||
|
|
||||||
The lossless wiki writer spells a node or mark wiki markup has no spelling for as Jira's own
|
Wiki markup has no spelling for some nodes and marks, a layout among them. The lossless wiki
|
||||||
`{adf:display=block}` or `{adf:display=inline}` macro around the node's ADF JSON, so the round-trip
|
writer wraps each such node's ADF JSON in Jira's own `{adf}` macro: `{adf:display=block}` for a
|
||||||
holds and Jira still renders the document. The lossy wiki writer ships beside it for consumers who
|
block node, `{adf:display=inline}` for an inline node or a marked run. The round-trip holds, and
|
||||||
want wiki markup alone: it drops the form of what wiki markup cannot spell and keeps its content.
|
Jira still renders the document. The lossy wiki writer ships beside it for consumers who want wiki
|
||||||
|
markup alone: it drops the form of what wiki markup cannot spell and keeps its content.
|
||||||
|
|
||||||
## `htmlToAdf` reads any HTML, with no option and no second call
|
## `htmlToAdf` reads any HTML, with no option and no second call
|
||||||
|
|
||||||
2026-11-15, a developer panel. Goals 6, 8 and 12. Valid while the dialect and foreign HTML read
|
2026-11-15, a developer panel. Goals 6, 8 and 12. Valid while the dialect and foreign HTML read
|
||||||
without ambiguity in one reader.
|
without ambiguity in one reader. Lands with `todo.md` item 137, which ends "Other HTML stays
|
||||||
|
refused" in §`htmlToAdf` also reads the dialect as a browser serializes it.
|
||||||
|
|
||||||
HTML from an email, a CMS or an editor reads through `htmlToAdf(html)`, as the dialect does; foreign
|
HTML from an email, a CMS or an editor will read through `htmlToAdf(html)`. An element that claims
|
||||||
elements sort as §Foreign HTML sorts three ways says. The bot, viewer/editor and LLM-pipeline
|
the dialect, by a `data-adf` attribute or an `adf-` class, reads only as the dialect, and stays
|
||||||
readers each picked it 3 of 3 over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`:
|
refused where that reading fails, so an edited carry element is still `unmappable-html`. Every other
|
||||||
none of them knows up front whether HTML is foreign, and a flag or a second name makes them guess.
|
element sorts as §Foreign HTML reads best effort and is never refused says.
|
||||||
|
|
||||||
|
A panel of three developers, one each for the bot, the viewer/editor app and the LLM pipeline, all
|
||||||
|
picked this over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`. None of them knows
|
||||||
|
up front whether HTML is foreign, so a flag or a second name makes them guess.
|
||||||
|
|||||||
@@ -50,8 +50,8 @@ diagrams drawn into images.
|
|||||||
Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is
|
Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is
|
||||||
published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with
|
published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with
|
||||||
`<!-- Space: DOCS -->` as `unmappable-html`, and refuses `<!-- Include: -->` the same way, because
|
`<!-- Space: DOCS -->` as `unmappable-html`, and refuses `<!-- Include: -->` the same way, because
|
||||||
a comment is content ADF cannot hold (`docs/decisions.md` §Foreign HTML sorts three ways). Both
|
the markdown readers refuse raw HTML today. Once `todo.md` item 138 reads it through `htmlToAdf`,
|
||||||
refusals follow that entry.
|
both comments drop (`docs/decisions.md` §Foreign HTML reads best effort and is never refused).
|
||||||
|
|
||||||
## What the audience would expect
|
## What the audience would expect
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -192,7 +192,7 @@ is the fence.
|
|||||||
## Raw HTML in input
|
## Raw HTML in input
|
||||||
|
|
||||||
CommonMark input may contain raw HTML. Every markdown reader routes each construct through the
|
CommonMark input may contain raw HTML. Every markdown reader routes each construct through the
|
||||||
foreign HTML element mapping (`docs/decisions.md` §Foreign HTML sorts three ways) — ADF has no
|
foreign HTML element mapping (`docs/decisions.md` §Foreign HTML reads best effort and is never refused) — ADF has no
|
||||||
raw-HTML node, so a construct without a mapping, comments and processing instructions included, is
|
raw-HTML node, so a construct without a mapping, comments and processing instructions included, is
|
||||||
an error result naming it. The flavour never emits raw HTML.
|
an error result naming it. The flavour never emits raw HTML.
|
||||||
|
|
||||||
|
|||||||
@@ -15,9 +15,9 @@
|
|||||||
| 192 | 0.4.0 | | owner | **Spec each ADF node's and mark's Jira wiki spelling in `spec/wiki.md`, sourced from Atlassian's text formatting notation help, with the wiki calls' names a developer panel picks.** | 2 | 2 | 1 | 3 | 3 | 11 by 3 | 2.5 |
|
| 192 | 0.4.0 | | owner | **Spec each ADF node's and mark's Jira wiki spelling in `spec/wiki.md`, sourced from Atlassian's text formatting notation help, with the wiki calls' names a developer panel picks.** | 2 | 2 | 1 | 3 | 3 | 11 by 3 | 2.5 |
|
||||||
| 193 | 0.4.0 | 192 | owner | **Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.** | 3 | 1 | 2 | 4 | 7 | 11 by 4 | 0.4 |
|
| 193 | 0.4.0 | 192 | owner | **Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.** | 3 | 1 | 2 | 4 | 7 | 11 by 4 | 0.4 |
|
||||||
| 194 | 0.4.0 | 193 | owner | **Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.** | 2 | 2 | 2 | 4 | 4 | 11 by 2 | 1.1 |
|
| 194 | 0.4.0 | 193 | owner | **Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.** | 2 | 2 | 2 | 4 | 4 | 11 by 2 | 1.1 |
|
||||||
| 195 | 0.4.0 | 193 | owner | **Read Jira wiki markup into ADF, `{adf}` carries included, as `spec/wiki.md` says.** | 4 | 1 | 2 | 5 | 8 | 11 by 5 | 0.3 |
|
| 195 | 0.4.0 | 193 | owner | **Read Jira wiki markup into ADF, `{adf}` macros included, as `spec/wiki.md` says.** | 4 | 1 | 2 | 5 | 8 | 11 by 5 | 0.3 |
|
||||||
| 196 | 0.4.0 | 194, 195 | owner | **Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.** | 1 | 2 | 1 | 2 | 2 | 3 by 2, 11 by 1 | 3.6 |
|
| 196 | 0.4.0 | 194, 195 | owner | **Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.** | 1 | 2 | 1 | 2 | 2 | 3 by 2, 11 by 1 | 3.6 |
|
||||||
| 137 | 0.4.0 | | decision | **Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.** | 2 | 1 | 2 | 3 | 4 | 12 by 6 | 3.3 |
|
| 137 | 0.4.0 | | decision | **Read foreign HTML in `htmlToAdf` best effort, never refusing it, as `docs/decisions.md` §Foreign HTML reads best effort and is never refused states.** | 2 | 1 | 2 | 3 | 4 | 12 by 6 | 3.3 |
|
||||||
| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.5 |
|
| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.5 |
|
||||||
| 107 | 0.4.0 | | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 3 | 1 | 3 | 5 | 5 | | 0.0 |
|
| 107 | 0.4.0 | | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 3 | 1 | 3 | 5 | 5 | | 0.0 |
|
||||||
| 170 | 0.4.0 | | owner | **Bundle the packed tarball with webpack, esbuild, Rollup and Bun in the gate, failing on any bundler warning, and run each bundle's round-trip in Node.** | 3 | 1 | 1 | 3 | 5 | | 0.0 |
|
| 170 | 0.4.0 | | owner | **Bundle the packed tarball with webpack, esbuild, Rollup and Bun in the gate, failing on any bundler warning, and run each bundle's round-trip in Node.** | 3 | 1 | 1 | 3 | 5 | | 0.0 |
|
||||||
@@ -49,13 +49,16 @@
|
|||||||
|
|
||||||
### 192. Spec each ADF node's and mark's Jira wiki spelling in `spec/wiki.md`, sourced from Atlassian's text formatting notation help, with the wiki calls' names a developer panel picks.
|
### 192. Spec each ADF node's and mark's Jira wiki spelling in `spec/wiki.md`, sourced from Atlassian's text formatting notation help, with the wiki calls' names a developer panel picks.
|
||||||
|
|
||||||
First of the items splitting item 148, under README goal 11. Confirm against a real Jira site that
|
Goal 11. The lossless writer carries what wiki markup cannot spell in Jira's `{adf}` macro, as
|
||||||
the renderer reads `{adf:display=block}` and `{adf:display=inline}` around ADF JSON, the carry
|
`docs/decisions.md` records. First confirm on a real Jira site that the renderer reads that macro
|
||||||
docs/decisions.md §Jira wiki markup carries what it cannot spell names; where it does not, ask
|
around ADF JSON; where it does not, ask before building the writers.
|
||||||
before building the writers. The spec names, per node and mark, the lossless writer's spelling, the
|
|
||||||
lossy writer's, and what the reader reads. A developer panel picks the names of the reader and both
|
The spec names, per node and mark, the lossless writer's spelling, the lossy writer's, and what the
|
||||||
writers, and whether the lossy writer is a call or an option (Goal 6.1, Goal 8's "nothing to
|
reader reads. A developer panel picks the names of the reader and both writers, and whether the
|
||||||
configure"); a writer panel of wiki-markup authors benches each spelling Jira's help leaves open.
|
lossy writer is a call or an option, under Goals 6.1 and 8. Its brief names the trap a wrong pick
|
||||||
|
sets: an app that saves through the lossy writer loses form on every save, with no refusal. A writer
|
||||||
|
panel of the wiki-markup authors in the README's `## Audience` settles each spelling Jira's help
|
||||||
|
leaves open.
|
||||||
|
|
||||||
### 193. Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.
|
### 193. Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.
|
||||||
|
|
||||||
@@ -64,25 +67,25 @@ mark; item 195's reader adds the round-trip property.
|
|||||||
|
|
||||||
### 194. Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.
|
### 194. Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.
|
||||||
|
|
||||||
The lossy wiki writer the maintainer asked for beside the lossless one, 2026-11-15, under Goal 7.
|
Goal 7. The maintainer asked for it beside the lossless writer, 2026-11-15. It spells as the
|
||||||
It shares the lossless writer's spellings and differs only where that writer would carry.
|
lossless writer does, except where that writer would use the `{adf}` macro.
|
||||||
|
|
||||||
### 195. Read Jira wiki markup into ADF, `{adf}` carries included, as `spec/wiki.md` says.
|
### 195. Read Jira wiki markup into ADF, `{adf}` macros included, as `spec/wiki.md` says.
|
||||||
|
|
||||||
A hand-written reader, as `htmlToAdf` is. Ships with the property that what the lossless writer of
|
A hand-written reader, as `htmlToAdf` is. Ships with the property that what the lossless writer of
|
||||||
item 193 writes reads back deep-equal, and with refusals whose codes come from the closed list.
|
item 193 writes reads back deep-equal, and with refusals whose codes come from the closed list.
|
||||||
|
|
||||||
### 196. Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.
|
### 196. Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.
|
||||||
|
|
||||||
Last of the items splitting item 148: a Quick start section per direction, the calls table, the
|
A Quick start section per direction, the calls table and the guarantees. The comparison tables
|
||||||
guarantees, and a row in the comparison tables per docs/decisions.md §The comparison tables list
|
gain a row, as the decision "The comparison tables list every ADF converter that starts and
|
||||||
every ADF converter that starts and converts.
|
converts" asks.
|
||||||
|
|
||||||
### 137. Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.
|
### 137. Read foreign HTML in `htmlToAdf` best effort, never refusing it, as `docs/decisions.md` §Foreign HTML reads best effort and is never refused states.
|
||||||
|
|
||||||
HTML from emails, CMSs and editors into ADF is the most asked need on the Atlassian developer
|
Reading HTML from emails, CMSs and editors is the most asked need on the Atlassian developer
|
||||||
community, README goal 12. It reads through `htmlToAdf` alone, with no option, as docs/decisions.md
|
community. A developer panel picked `htmlToAdf` itself, with no option, as `docs/decisions.md`
|
||||||
§`htmlToAdf` reads any HTML, with no option and no second call records.
|
records.
|
||||||
|
|
||||||
### 172. Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.
|
### 172. Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user