chore(api): close v1.9.0 engine-leak guard and metadata gaps#253
Merged
Conversation
…ages PublicApiNoEngineLeakTest pinned only eight document.* packages, while output, snapshot, theme, exceptions, and emoji are equally public and must stay free of com.demcha.compose.engine.* imports. Add all five to PUBLIC_API_ROOTS; each is already engine-clean so the guard passes and locks the property in. Engine-adjacent internals (layout, backend, templates, debug) stay excluded by design.
…CHANGELOG - DocumentSession.pageMargins(List<PageMarginRule>) gains @SInCE 1.9.0, matching its sibling 1.9.0 methods (viewerPreferences, pageIndex, toImage). - HeadlineRenderer / ContactRenderer / BannerRenderer become @deprecated(since = "1.9.0", forRemoval = true) with the @deprecated Javadoc leading "since 1.9.0; removed in 2.0.", matching CoverLetterTemplate and the api-stability deprecation ledger. - CHANGELOG in-progress header "v1.9.0 - unreleased" -> "v1.9.0 - Planned" so the release tooling rewrites it to the ISO date at cut time.
DemchaAV
added a commit
that referenced
this pull request
Jun 29, 2026
* chore(api): close v1.9.0 engine-leak guard and metadata gaps (#253) * test(api): extend the engine-leak guard to all public document.* packages PublicApiNoEngineLeakTest pinned only eight document.* packages, while output, snapshot, theme, exceptions, and emoji are equally public and must stay free of com.demcha.compose.engine.* imports. Add all five to PUBLIC_API_ROOTS; each is already engine-clean so the guard passes and locks the property in. Engine-adjacent internals (layout, backend, templates, debug) stay excluded by design. * docs(api): complete v1.9.0 since/deprecation metadata and date-ready CHANGELOG - DocumentSession.pageMargins(List<PageMarginRule>) gains @SInCE 1.9.0, matching its sibling 1.9.0 methods (viewerPreferences, pageIndex, toImage). - HeadlineRenderer / ContactRenderer / BannerRenderer become @deprecated(since = "1.9.0", forRemoval = true) with the @deprecated Javadoc leading "since 1.9.0; removed in 2.0.", matching CoverLetterTemplate and the api-stability deprecation ledger. - CHANGELOG in-progress header "v1.9.0 - unreleased" -> "v1.9.0 - Planned" so the release tooling rewrites it to the ISO date at cut time. * docs(readme): announce v1.9.0 "navigable" and add the v1.8->v1.9 migration guide (#254) - README "Release status" now names v1.9.0 (codename "navigable") as Latest stable, and the "What's new" section covers in-document navigation, the native TOC / page references / bookmarks, multi-section documents, the per-page-margin / bleed / row-layout additions, inline chips / SVG / emoji, and render-to-images. Install snippets stay at 1.8.0 (the release tooling flips them at cut time). - Add docs/roadmaps/migration-v1-8-to-v1-9.md — additive-only upgrade guide with a per-area TL;DR table, the one negative-margin behaviour note, the 2.0-bound shim deprecations, and the upgrade snippet. - Index the v1.8->v1.9 and the previously unlisted v1.7->v1.8 guides in docs/README.md. * docs(examples): gallery entries for inline chips, SVG, emoji, in-PDF navigation (#256) Four v1.9.0 features visible in a rendered document had no gallery presence. Add a row + detailed showcase section + a committed preview render for each, with the API names read off the runnable *Example classes: - Inline highlight chips (RichText.code / chip / highlight) — Core DSL. - Inline SVG icons (RichText.svgIcon) — Core DSL. - Colour emoji by shortcode (RichText.emoji) — Core DSL. - In-PDF navigation (anchor / linkTo / inlineLinkTo / shapeLinkTo) — Advanced SPI. The emoji preview uses the 44 KB shortcode showcase; the full emoji-gallery render is 3.9 MB, too large for a committed README asset. * deps(deps): bump the maven-minor-patch group across 3 directories with 2 updates (#259) Bumps the maven-minor-patch group with 2 updates in the / directory: [org.junit:junit-bom](https://github.com/junit-team/junit-framework) and [ch.qos.logback:logback-classic](https://github.com/qos-ch/logback). Bumps the maven-minor-patch group with 2 updates in the /benchmarks directory: [org.junit:junit-bom](https://github.com/junit-team/junit-framework) and [ch.qos.logback:logback-classic](https://github.com/qos-ch/logback). Bumps the maven-minor-patch group with 2 updates in the /examples directory: [org.junit:junit-bom](https://github.com/junit-team/junit-framework) and [ch.qos.logback:logback-classic](https://github.com/qos-ch/logback). Updates `org.junit:junit-bom` from 6.1.0 to 6.1.1 - [Release notes](https://github.com/junit-team/junit-framework/releases) - [Commits](junit-team/junit-framework@r6.1.0...r6.1.1) Updates `ch.qos.logback:logback-classic` from 1.5.34 to 1.5.37 - [Release notes](https://github.com/qos-ch/logback/releases) - [Commits](qos-ch/logback@v_1.5.34...v_1.5.37) Updates `org.junit:junit-bom` from 6.1.0 to 6.1.1 - [Release notes](https://github.com/junit-team/junit-framework/releases) - [Commits](junit-team/junit-framework@r6.1.0...r6.1.1) Updates `ch.qos.logback:logback-classic` from 1.5.34 to 1.5.37 - [Release notes](https://github.com/qos-ch/logback/releases) - [Commits](qos-ch/logback@v_1.5.34...v_1.5.37) Updates `org.junit:junit-bom` from 6.1.0 to 6.1.1 - [Release notes](https://github.com/junit-team/junit-framework/releases) - [Commits](junit-team/junit-framework@r6.1.0...r6.1.1) Updates `ch.qos.logback:logback-classic` from 1.5.34 to 1.5.37 - [Release notes](https://github.com/qos-ch/logback/releases) - [Commits](qos-ch/logback@v_1.5.34...v_1.5.37) --- updated-dependencies: - dependency-name: org.junit:junit-bom dependency-version: 6.1.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: maven-minor-patch - dependency-name: ch.qos.logback:logback-classic dependency-version: 1.5.37 dependency-type: direct:development update-type: version-update:semver-patch dependency-group: maven-minor-patch - dependency-name: org.junit:junit-bom dependency-version: 6.1.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: maven-minor-patch - dependency-name: ch.qos.logback:logback-classic dependency-version: 1.5.37 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: maven-minor-patch - dependency-name: org.junit:junit-bom dependency-version: 6.1.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: maven-minor-patch - dependency-name: ch.qos.logback:logback-classic dependency-version: 1.5.37 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: maven-minor-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * ci: bump actions/cache from 5 to 6 in the github-actions group (#258) Bumps the github-actions group with 1 update: [actions/cache](https://github.com/actions/cache). Updates `actions/cache` from 5 to 6 - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](actions/cache@v5...v6) --- updated-dependencies: - dependency-name: actions/cache dependency-version: '6' dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Artem Demchyshyn <132658418+DemchaAV@users.noreply.github.com> * feat(examples): auto-render the version-stamped README hero banner on release (#260) The README hero (assets/readme/repository_showcase_render.png) carried a hardcoded version constant and was rasterised by hand, so it drifted — it still read v1.8.0 while the repo was on 1.9.0. Now it is single-sourced and rendered straight from the engine: - EngineDeckExample reads its version + codename from a Maven-filtered banner.properties (version=@project.version@, codename=navigable) instead of hardcoded constants, so the hero always carries the reactor version. - The new ReadmeBannerRenderer writes the PNG straight from the engine via DocumentSession.toImage(0, dpi) — no render-to-PDF-then-PdfPageRasterizer round-trip. EngineDeckExample.renderBannerImage shares the banner composition with the (kept) PDF generateBanner via composeBannerInto. - cut-release.ps1 re-renders the banner after the version bump and stages it in the release commit (gated under -not -SkipShowcase), so the committed hero ships in lockstep with every tag. - VersionConsistencyGuardTest fails the build if banner.properties stops sourcing the version from @project.version@; ReadmeBannerRendererTest covers the render, the PNG write, and that filtering actually resolved. The hero keeps its tight pageSize crop: the whole page is the banner via pageBackground, which bleed() does not replace. * docs(readme): add the graph-compose-emoji install snippet for the v1.9.0 emoji feature (#261) The "What's new in v1.9" block names colour emoji via the independently-versioned graph-compose-emoji module, but the install section gave no coordinate for it — only the fonts companion artifact had a copy-paste dependency block. Add a parallel graph-compose-emoji (1.0.0) snippet, noting emoji is opt-in (the bundle stays fonts-only) and that an unknown shortcode falls back to literal text. * fix(release-script): recompile examples in the banner step so the hero stamps the bumped version Render-ReadmeBanner ran `exec:java ReadmeBannerRenderer` without compiling the examples module. banner.properties is filtered to ${project.version} at examples-compile time, and the cut never recompiles examples after the Step-1 version bump — so the re-rendered hero carried the PREVIOUS release version (e.g. a v1.9.0 cut would have stamped "v1.8.0"). Add `compile` to the exec so the module is rebuilt at the bumped version and banner.properties re-filters before the render. * Release v1.9.0 * post-release: flip showcase links back to /blob/develop * docs: add first-document, capabilities, diagrams, and business-templates guides (#263) Add four developer-facing pages and wire them into the docs index. - first-document.md — a five-minute path from an empty project to a rendered PDF: the smallest document, a multi-section custom flow, the built-in template shortcut, and server streaming. - capabilities.md — a feature-to-API map giving the main call, the stability tier, and a guide link for each capability; the API stability policy stays authoritative for the contract. - diagrams.md — Mermaid decision diagrams for the authoring path, content placement, output destination, and document lifecycle. - templates/business-templates.md — the built-in InvoiceTemplateV2 and ProposalTemplateV2 compose-first contract, end to end, including the server-stream variant. getting-started.md gains a one-line pointer to first-document.md, and the docs README persona table and category index link the new pages. * ci(deploy-web): drop the v* tag trigger that fails every release (#262) The GitHub Pages deploy fired on both the main push and the v* release tag, but the tag run failed every release: Pages refuses to deploy from a tag ref (the github-pages environment only allows main), so it produced a red X without ever deploying — and via cancel-in-progress could race-cancel the good main run. The unconditional `push: branches: [main]` trigger (no paths filter) already covers releases reliably, so the tag trigger is redundant. Remove it. --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@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.
Why
Two gaps in the public-API surface of the in-progress v1.9.0 release.
PublicApiNoEngineLeakTestdocuments itself as pinning "everycom.demcha.compose.engine.*import leaking into the public API surface", butPUBLIC_API_ROOTSlisted only eightdocument.*packages —output,snapshot,theme,exceptions, andemojiwere never scanned. All five arepublic (each carries a
package-info), and three gained new public types thiscycle (
DocumentViewerPreferences/DocumentPageNumberinginoutput,PageIndex/PageReferenceinsnapshot,EmojiLibraryinemoji), so anengine import into any of them would land in Stable public API undetected.
Separately, three pieces of 1.9.0 metadata were inconsistent:
DocumentSession.pageMargins(...)shipped without the@since 1.9.0its sixsibling new methods carry; the three deprecated CV-renderer shims carried
@Deprecated(forRemoval = true)without thesincethat their siblingCoverLetterTemplateanddocs/api-stability.md§3 both require; and thein-progress CHANGELOG header read
— unreleased, which the release tooling doesnot match (it dates
## v<ver> — Planned), so the shipped CHANGELOG would havestayed undated.
What changed
PublicApiNoEngineLeakTest.PUBLIC_API_ROOTSnow also scansdocument/{output,snapshot,theme,exceptions,emoji}. All five are alreadyengine-import-free, so the guard passes immediately and locks the property in.
The engine-adjacent internal trees (
layout,backend,templates,debug)stay excluded by design — they legitimately depend on the engine.
DocumentSession.pageMargins(List<PageMarginRule>)gains@since 1.9.0,matching
viewerPreferences/pageIndex/toImage(s).HeadlineRenderer/ContactRenderer/BannerRendererbecome@Deprecated(since = "1.9.0", forRemoval = true), and their@deprecatedJavadoc leads with
since 1.9.0; removed in 2.0.— thesincemarks when thedeprecation took effect, matching
CoverLetterTemplateand the §3 ledger.## v1.9.0 — unreleased→## v1.9.0 — Plannedso the release tooling rewrites it to the ISO date at cut time.
Verification
./mvnw -B -ntp clean verify -pl .→ BUILD SUCCESS, 1607 tests, 0failures, 0 javadoc warnings. The widened
PublicApiNoEngineLeakTeststays green(all five added packages are engine-clean);
VersionConsistencyGuardTeststaysgreen with the
Plannedheader. No runtime code changed — a test allow-list,Javadoc
@since, deprecation annotations, and a CHANGELOG header only; no publicAPI surface added or altered.
Lane: test + canonical (docs/metadata) — guard coverage plus 1.9.0
public-API metadata, no behavioural change.