mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-18 22:25:44 +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
|
||||
- The carry fence names the node type
|
||||
- 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
|
||||
- Directives under `!adf:`
|
||||
- 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 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
|
||||
- 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
|
||||
|
||||
## 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.
|
||||
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
|
||||
managers, engineers and support agents working in Atlassian products through a plugin or another
|
||||
UI. They know markdown and not ADF, and rely on every spelling saying what it means to them.
|
||||
Behind those apps, the people who read and write the markdown, the HTML and the Jira wiki markup:
|
||||
product managers, engineers and support agents working in Atlassian products through a plugin or
|
||||
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
|
||||
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:
|
||||
`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
|
||||
for a bare container, a comment or a script. Lands with `todo.md` item 137.
|
||||
2026-08-23, the sort 2026-09-20, best effort 2026-11-15, the maintainer. Goals 7 and 12. Valid while
|
||||
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
|
||||
silent drop of content:
|
||||
HTML from emails, CMSs and editors guarantees nothing, so no foreign element is refused. Each reads
|
||||
one of two ways:
|
||||
|
||||
- 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.
|
||||
- Content ADF cannot hold is an error result naming it. A comment is one: a person wrote those
|
||||
words, and neither of Atlassian's schemas holds them — `annotation`'s `inlineComment` carries an
|
||||
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.
|
||||
- What no reader sees drops whole: `<script>` and `<style>` with their text, and a comment, since a
|
||||
browser shows none of it and an email's conditional comments are markup.
|
||||
|
||||
`<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`
|
||||
attribute is not read at `0.4.0`: the `textColor` and `backgroundColor` it could reach cost more
|
||||
than they buy.
|
||||
`nestedExpand` inside another; an empty one holds an empty paragraph, since `expand` requires
|
||||
content. A `style` attribute is not read at `0.4.0`: the `textColor` and `backgroundColor` it could
|
||||
reach cost more than they buy.
|
||||
The three markdown readers share one parser, so they take the same set.
|
||||
|
||||
## Names stay text
|
||||
@@ -1448,22 +1446,28 @@ alt text.
|
||||
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.
|
||||
|
||||
## 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.
|
||||
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
|
||||
`{adf:display=block}` or `{adf:display=inline}` macro around the node's ADF JSON, so the round-trip
|
||||
holds and 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.
|
||||
Wiki markup has no spelling for some nodes and marks, a layout among them. The lossless wiki
|
||||
writer wraps each such node's ADF JSON in Jira's own `{adf}` macro: `{adf:display=block}` for a
|
||||
block node, `{adf:display=inline}` for an inline node or a marked run. The round-trip holds, and
|
||||
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
|
||||
|
||||
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
|
||||
elements sort as §Foreign HTML sorts three ways says. The bot, viewer/editor and LLM-pipeline
|
||||
readers each picked it 3 of 3 over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`:
|
||||
none of them knows up front whether HTML is foreign, and a flag or a second name makes them guess.
|
||||
HTML from an email, a CMS or an editor will read through `htmlToAdf(html)`. An element that claims
|
||||
the dialect, by a `data-adf` attribute or an `adf-` class, reads only as the dialect, and stays
|
||||
refused where that reading fails, so an edited carry element is still `unmappable-html`. Every other
|
||||
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
|
||||
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
|
||||
a comment is content ADF cannot hold (`docs/decisions.md` §Foreign HTML sorts three ways). Both
|
||||
refusals follow that entry.
|
||||
the markdown readers refuse raw HTML today. Once `todo.md` item 138 reads it through `htmlToAdf`,
|
||||
both comments drop (`docs/decisions.md` §Foreign HTML reads best effort and is never refused).
|
||||
|
||||
## What the audience would expect
|
||||
|
||||
|
||||
+1
-1
@@ -192,7 +192,7 @@ is the fence.
|
||||
## Raw HTML in input
|
||||
|
||||
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
|
||||
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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
@@ -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.
|
||||
|
||||
First of the items splitting item 148, under README goal 11. Confirm against a real Jira site that
|
||||
the renderer reads `{adf:display=block}` and `{adf:display=inline}` around ADF JSON, the carry
|
||||
docs/decisions.md §Jira wiki markup carries what it cannot spell names; where it does not, ask
|
||||
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
|
||||
writers, and whether the lossy writer is a call or an option (Goal 6.1, Goal 8's "nothing to
|
||||
configure"); a writer panel of wiki-markup authors benches each spelling Jira's help leaves open.
|
||||
Goal 11. The lossless writer carries what wiki markup cannot spell in Jira's `{adf}` macro, as
|
||||
`docs/decisions.md` records. First confirm on a real Jira site that the renderer reads that macro
|
||||
around ADF JSON; where it does not, ask 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 writers, and whether the
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
The lossy wiki writer the maintainer asked for beside the lossless one, 2026-11-15, under Goal 7.
|
||||
It shares the lossless writer's spellings and differs only where that writer would carry.
|
||||
Goal 7. The maintainer asked for it beside the lossless writer, 2026-11-15. It spells as the
|
||||
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
|
||||
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`.
|
||||
|
||||
Last of the items splitting item 148: a Quick start section per direction, the calls table, the
|
||||
guarantees, and a row in the comparison tables per docs/decisions.md §The comparison tables list
|
||||
every ADF converter that starts and converts.
|
||||
A Quick start section per direction, the calls table and the guarantees. The comparison tables
|
||||
gain a row, as the decision "The comparison tables list every ADF converter that starts and
|
||||
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
|
||||
community, README goal 12. It reads through `htmlToAdf` alone, with no option, as docs/decisions.md
|
||||
§`htmlToAdf` reads any HTML, with no option and no second call records.
|
||||
Reading HTML from emails, CMSs and editors is the most asked need on the Atlassian developer
|
||||
community. A developer panel picked `htmlToAdf` itself, with no option, as `docs/decisions.md`
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user