From 5be752522b533f008d1a9f19b41ccb7b3919c727 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 17 Oct 2026 22:14:49 +0200 Subject: [PATCH] =?UTF-8?q?Answer=20product-owner=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=201=20=F0=9F=9F=A1;=20say=20what=20Maintain=20and?= =?UTF-8?q?=20Achieve=20mean=20in=20the=20goals'=20intro,=20and=20reword?= =?UTF-8?q?=20goal=204's=20and=206's=20signals=20and=20the=20contributor?= =?UTF-8?q?=20line?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 11 ++++++----- todo.md | 9 +++++---- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9f83a6d..50cdb6b 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,8 @@ Nothing throws. `code` is from a closed list, so a `switch` with no `default` co ## Goals -The most useful ADF conversion library available, judged by these goals, in priority order: +The most useful ADF conversion library available, judged by these goals. A Maintain goal holds +whatever it costs; the Achieve goals are weighed against each other in the order listed. 1. **Maintain:** Lossless, and every call returns a result, never a throw. 2. **Maintain:** ADF is the hub. @@ -167,13 +168,13 @@ The most useful ADF conversion library available, judged by these goals, in prio - Counter-signal: issues asking what a call does, or saying it did something else, rise. - Why: users won by a vague pitch come back as confusion. 4. **Achieve:** Each format reads and writes as its standard says. - - Signal: the exceptions [The guarantees](#the-guarantees) list fall in number. + - Signal: fewer exceptions are listed under [The guarantees](#the-guarantees). - Counter-signal: breaking releases rise. - Why: conformance bought by changing stored formats costs every consumer a migration. 5. **Maintain:** Our markdown is CommonMark, extended only where CommonMark has no spelling. 6. **Achieve:** No surprises: output reads and edits the way its audience expects. - - Signal: reader panels pick the output the library already writes. - - Counter-signal: `spec/flavour.md` gains a special case for each panel's verdict. + - Signal: readers shown the candidate outputs pick the one the library already writes. + - Counter-signal: `spec/flavour.md` gains a special case for each such pick. - Why: output fitted case by case is output no reader can predict. 1. **Maintain:** A function's name says which markdown it reads or writes. 7. **Maintain:** Lossy conversion drops form, never content. @@ -206,7 +207,7 @@ managers, engineers and support agents working in Atlassian products through a p UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. Contributors, human or agent, who change the source. They rely on each concern having one obvious -place, and on the gate catching a change that breaks a guarantee. +place, and on CI failing a change that breaks a guarantee. ## Other ADF converters diff --git a/todo.md b/todo.md index 1b72ff1..a72fc6a 100644 --- a/todo.md +++ b/todo.md @@ -115,7 +115,7 @@ run it carries may differ from today's, which changes lossless output (§The for ### 91. Spell an emphasis once across the code spans, an emphasis or link once across the hard breaks, dates, emoji, inline cards, mentions and statuses between two nodes it marks, and an emphasis across inline media, in both writers. -Item 95 lets the joined spelling be tried and kept only where it reads back. No +It needs item 95, which lets the joined spelling be tried and kept only where it reads back. No reader marks a hard break, so `*One\` then `Two*` writes back as `_One_\` then `_Two_`, and a link typed across a line as two links. No reader gives those other nodes a mark Atlassian's schema withholds from them, and none gives code text a mark but a link. So `**Ping !adf:mention[@A]{id=x} @@ -165,7 +165,8 @@ three directories. ### 73. Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions. -Each post links the GitHub repository, the README's comparison table and a README that opens with what the package is. Before +Blocked by every other `0.3.0` item (the maintainer, 2026-10-14): the posts announce the finished +release. Each post links the GitHub repository, the README's comparison table and a README that opens with what the package is. Before posting, set `converter-comparison/run.sh`'s pins to each package's latest version, `@larvit/adf-codec@0.3.0` included, and `--before` to today. Run it, then bring the README table, its versions and its date in step with the output. We draft each post for the place it goes; the @@ -256,7 +257,7 @@ exception and count one fewer. whose info string is `carry`. Under the `docs/decisions.md` entry "The carry fence names the node type", that is an ordinary code language, so the property reaches `readCarriedBlock`'s refusals only where a random edit lands in a canonical document. Write `adf:` and `adf:` fences, canonical -and hostile. Technical principle: for pure logic over many inputs, prefer a property test. Found by the technical-principles audit, 2026-10-04. +and hostile. Technical principle: for pure logic over many inputs, prefer a property test, so the property must reach the fenced carry's refusals itself. Found by the technical-principles audit, 2026-10-04. ### 77. Read the input once into a plain copy, so an accessor property or a throwing Proxy yields `not-an-adf-document` and every call returns a result. @@ -286,7 +287,7 @@ are API). Found by the README-goals audit of item 83, 2026-10-11. ### 72. Re-create `gitea.larvit.se/larvit/adf-codec` as a read-only pull mirror of GitHub, its issues and Actions off and its description pointing at GitHub. -The maintainer does this. Gitea +Blocked by every other `0.4.0` item (the maintainer, 2026-10-05). The maintainer does this. Gitea cannot convert an existing repository to a mirror, so the copy is deleted and re-created. That drops the copy's commit hashes from before the 2026-10-04 history rewrite, and its Actions secrets. The Gitea copy holds no issues or releases to move. Actions stay off on the mirror: Gitea runs