Cut v0.4.0, and make the docs describe the code that exists - #27
Merged
Conversation
The README advertised a library nobody could install. Its feature table promised `fitText`, `FontMetrics`, `outline()`, `DeckExport`, `replaceData` and `documentKind`, while the install snippet pointed at `from: "0.3.0"` — and v0.3.1, the newest tag, contains none of them. The whole "Measure & trust" program had shipped into an [Unreleased] section 400 lines long. So: promote it. [Unreleased] becomes 0.4.0, dated, with the program's theme stated up front; README installs 0.4.0; ROADMAP marks the v0.4 program shipped rather than open-ended. The section it promotes was also malformed — three separate `### Changed` headings inside one version — and silent about the most recent work. Now recorded, each verified against the code rather than the commit messages: - `slides.add(layout:)` → `add(clonedFrom:)`, a public rename with a deprecated shim, which had gone entirely undocumented. - `renderSVGReportingProblems` and `Shape.markAsPlaceholder`, both new public API. - `ShapeCollection.count`/subscript no longer walking the whole tree. - Builders writing real title placeholders, so generated decks stop being headless. - The Linux SIGSEGV: `<?target?>`, a dataless processing instruction, is a NULL dereference in libxml2 via `XMLParser` — a denial of service on untrusted input, since Rostrum opens files it did not write. That root-cause writeup existed only inside a lift-up plan. Which is the other half of this. Six audit artifacts — 236KB of routing tables, citation gates and cross-model reviews — sat at the repo root, and one of them was the only record of a security fix. Their durable findings move to where they are looked for: what shipped to CHANGELOG, what was deliberately not done to a new ROADMAP "Deferred" section. The scratch is gone from the tree and gitignored so the next audit does not re-land it. Two claims that were simply untrue are now true: ARCHITECTURE promised an orphan-audit API and an opt-in `prune()`, neither of which exists, and ROADMAP said read limits default to `.unlimited` when they have defaulted to 4 GiB since the hardening pass. One code change, because the warning it fixed was load-bearing: `SVGRenderer.render` bound a `dom` it never used, and deleting the call would have been wrong — every other read goes through `existingSpTree`, which swallows the parse with `try?`. It is the one thing that turns a malformed slide part into a thrown error instead of a blank slide. Now `_ =`, with a comment saying so. The library builds warning-free. `./scripts/verify.sh` green: Rostrum, LecternCore, README snippets, the macOS and iOS app builds, and the app-hosted tests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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
1 participant
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.
Two things were out of step with the code: the released version, and the docs.
The repo now matches local truth
PR #25 — 24 commits your main checkout was sitting on, including a Linux DoS fix — was open and green but unlanded. It's merged (merge commit, so the root-cause messages survive). Re-verified with the full
./scripts/verify.shgate before merging, and the merged tree is byte-identical to the tip that passed.v0.4.0, because the README advertised a library nobody could install
The feature table promised
fitText,FontMetrics,outline(),DeckExport,replaceDataanddocumentKind. The install snippet saidfrom: "0.3.0". v0.3.1 — the newest tag — contains none of them. The entire "Measure & trust" program had shipped into a 400-line[Unreleased].So
[Unreleased]becomes## [0.4.0] — 2026-08-17, README installs0.4.0, and ROADMAP marks the v0.4 program shipped rather than open-ended.What the CHANGELOG was missing
That section was malformed — three separate
### Changedheadings inside one version — and silent about the newest work. Each entry below was verified against the source, not the commit messages:slides.add(layout:)→add(clonedFrom:)— a public rename with a deprecated shim, previously undocumented anywhere.renderSVGReportingProblemsandShape.markAsPlaceholder— new public API.ShapeCollection.count/subscript no longer walking the whole tree.<?target?>— a dataless processing instruction — is a NULL dereference in libxml2 viaXMLParser: a denial of service on untrusted input, since Rostrum opens files it did not write. That root-cause writeup existed only inside a lift-up plan.236KB of audit scratch, one of which held a security writeup
Six lift-up/burn-down artifacts sat at the repo root. Their durable findings moved to where people look for them — what shipped to
CHANGELOG.md, what was deliberately not done to a new ROADMAP "Deferred" section (effective-frame inheritance, kerning/shaping,SVGRenderergolden-file tests,DeckRendererat 923 lines, the headless decks already written). The scratch is gone and gitignored so the next audit doesn't re-land it.Two claims that were untrue
docs/ARCHITECTURE.mdpromised an orphan-audit API and an opt-inprune(). Neither exists; now stated as intended-but-not-implemented, alongside thereadWarningsreporting that is real.ROADMAP.mdsaid read limits default to.unlimited. They have defaulted to 4 GiB since the hardening pass.I checked every backticked API in README, ARCHITECTURE and COOKBOOK against
Sources/—prune()was the only phantom. The 178 preset geometries and 150-style catalog both check out.One code change
SVGRenderer.renderbound adomit never used. Deleting the call would have been wrong: every other read goes throughexistingSpTree, which swallows the parse withtry?, so this is the one thing that turns a malformed slide part into a thrown error instead of a silently blank slide. Now_ =with a comment saying why. The library builds warning-free.Verification
./scripts/verify.shgreen — Rostrum, LecternCore, README snippets, macOS and iOS app builds, and the app-hosted tests.Still needs your call: tagging
v0.4.0once this lands (the README now points at it), and pruning 9 fully-merged remote branches — one of which,burndown/deck-workbench-20260805, is what your main checkout currently tracks.