docs(changelog): rewrite the v2.1.0 section as release notes#444
Merged
Conversation
The section read as the journal it was written as: 44 bullets in commit order, 17 of them consecutive PPTX implementation slices, several superseded by later ones. It ships verbatim into the GitHub Release, so a reader met the backend's history rather than what it does. Restructure it around what a reader needs — Highlights, Public API, PPTX backend, Fixed, Templates, Documentation and examples, Build and compatibility, and a Known limitations section the notes previously had no equivalent of. 329 lines become 216 without dropping a shipped fact. Three statements were wrong rather than merely verbose, and are corrected rather than reworded: - Determinism was advertised as "renders byte-identical decks across runs" with no caveat. It is opt-in and off by default: the SPI provider that buildPptx(Path) resolves never enables it, so the convenience methods stream with live timestamps. The notes now say so, and Known limitations repeats it. - "First capability slice: rectangle shapes, ellipses, and lines" described an intermediate state that the following bullets already superseded with text, tables, images, paths and transforms. - A Tests bullet claimed a default-output-file failure mode whose test was deleted with the no-arg buildPptx() overload. Clipping was also split across a slice and its later correction; it is now one statement about the shipped behaviour. Every mechanism claim was verified against the code rather than carried over: the decoration offsets (0.10 / 0.28 / 0.05 em) against PdfTextDecorations, the once-per-family substitution warning against PptxRenderEnvironment, the duplicate-handler rejection against Builder.addHandler, the 38/24/10/4 capability counts against the matrix, the record component counts against the v2.0.0 tag, and every API name against source. The twin-output shape count (69 native, one picture) and the PDF/PPTX geometry match were measured from the emitted artifacts. Verified: full reactor clean verify green (1522 tests, 0 failures); the release workflow's own awk extraction yields the 216-line section; both linked documents resolve on disk.
The capability summary said 10 of the 38 tracked capabilities "render natively with an approximated styling detail". Reading all ten rows rather than the count shows only about half are that. The others lose something: inline SVG falls back to a transparent PNG for arbitrary clips and off-viewBox art, bookmarks after the first on a page are dropped because PPTX has no outline tree, and metadata's producer value has no OPC field at all. A reader with a bookmark-heavy document would have taken that sentence to mean the only cost was styling, shipped a deck, and silently lost the navigation. Split the sentence so the partial group is not characterised as one thing, and add the three content-losing cases to Known limitations, which previously listed only the cosmetic approximations.
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.
Why
The v2.1.0 section reads as the journal it was written as: 44 bullets in commit order, 17 of them consecutive PPTX implementation slices, several superseded by later ones.
release.ymlships it verbatim into the GitHub Release, so a reader meets the backend's development history instead of what it does.What changed
Restructured around what a reader needs — Highlights · Public API · PPTX backend · Fixed · Templates · Documentation and examples · Build and compatibility · Known limitations (the notes previously had no equivalent of the last one). 329 lines → 216, without dropping a shipped fact.
Three statements were wrong, not merely verbose, and are corrected rather than reworded:
buildPptx(Path)resolves never enables it, so the convenience methods stream with live timestamps. Now stated in both the PPTX section and Known limitations.default-output-filefailure mode whose test was deleted along with the no-argbuildPptx()overload.Clipping was also split across a slice and its later correction; it is now one statement about the shipped behaviour.
Every claim verified against code, not memory
The changelog is the description, so each mechanism claim was checked:
PdfTextDecorations:29/36/39PptxRenderEnvironment:279/286addHandlerrejects a duplicate payload typePptxFixedLayoutBackend:833-841SectionNode13→14,LineNode17→18v2.0.0tagtwin-output1 page = 1 slide @ 960×540;engine-deck4 = 4 @ 841.89×595.28Verification
./mvnw -B -ntp clean verify— BUILD SUCCESS, 1522 tests, 0 failures.release.yml's own awk extraction yields the 216-line section.Not done here
The runbook's manual step — opening the decks in PowerPoint for Windows to confirm no repair prompt — is not something this environment can perform. The decks are structurally valid (OPC packages verified, correct slide counts, native shapes present), but that is not the same check. Files:
examples/target/generated-pdfs/flagships/{twin-output,engine-deck,maven-banner}.pptx.