Skip to content

chore(api): graduate the SVG surface from beta to stable - #598

Merged
DemchaAV merged 1 commit into
developfrom
chore/svg-beta-graduation
Aug 24, 2026
Merged

chore(api): graduate the SVG surface from beta to stable#598
DemchaAV merged 1 commit into
developfrom
chore/svg-beta-graduation

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Aug 24, 2026

Copy link
Copy Markdown
Owner

Why

The SVG surface has carried @Beta since 1.8.0 with an explicit exit condition — "while the surface hardens against real-world exporter output". That condition is met: the stroke/colour/unit hardening landed through 1.8.x (#180, #184#186, #193), clip-path support in 1.9.0, and the opacity family plus the approximation warnings in #596 — while the API shape itself has not moved since 1.9.0, four minors of real use (the 2.0 line only relocated the files). The stability policy in docs/api-stability.md says an Experimental surface graduates "typically by the next minor release", and its own registry of current @Beta carriers already lists only NodeDefinition and the PPTX backend — the code disagreed with the policy doc. The marker was also internally inconsistent: inlineSvgIcon / RichText.svgIcon and the emoji pipeline were built on @Beta SvgIcon without carrying the annotation themselves.

What changed

  • Eight annotation sites dropped: SvgIcon, SvgPath (class-level), PathBuilder.svg(svgPath), both AbstractFlowBuilder.addSvgIcon(...) overloads and ShapeContainerBuilder.path(w, h, svgPath) (these three used the fully-qualified @com.demcha.compose.document.api.Beta form — a plain-text @Beta grep misses them), and DocumentPaint.LinearAxis / RadialCircle. The paints graduate together with the reader that emits them: SvgIcon.Layer exposes DocumentPaint publicly, so a beta paint under a stable icon would re-create the same inconsistency this PR closes.
  • The four "Beta:" Javadoc paragraphs removed (SvgIcon, SvgPath, document.svg package-info, and the "may shift while that reader hardens" caveats on both paint records) — the surrounding docs already state the supported subset, the out-of-scope list, and each normalization contract, which is the stable promise. One stale test comment ("would DoS the @beta reader") updated alongside.
  • CHANGELOG ### Public API entry under v2.2.1 — Planned calls the transition out explicitly, as the policy requires, and names the two remaining @Beta carriers (NodeDefinition Extension SPI, PPTX backend), which now match docs/api-stability.md exactly — no doc edit needed there.
  • No behaviour, signature, or binary change — annotation and Javadoc only. BetaAnnotationDocumentationTest pins the annotation's shape, not its carriers, so no test changes.

Verification

Full reactor gate ./mvnw -B -ntp clean verify -pl :graph-compose-core,…,:graph-compose-coverage -amBUILD SUCCESS (exit 0, unpiped), and the Javadoc gate ./mvnw -B -ntp javadoc:javadocBUILD SUCCESS — the removed {@link Beta} references leave no dangling links. japicmp stays green: annotation removal is not a binary-compatibility event, and the plugin carries no @Beta exclusion that could have been load-bearing.

Lane: canonical (document.svg, document.dsl, document.style) — annotation/docs only.

Follow-up to #596 (the hardening pass this graduation was gated on).

@DemchaAV
DemchaAV merged commit 9de5bf2 into develop Aug 24, 2026
12 checks passed
@DemchaAV
DemchaAV deleted the chore/svg-beta-graduation branch August 24, 2026 08:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant