chore(api): graduate the SVG surface from beta to stable - #598
Merged
Conversation
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
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 SVG surface has carried
@Betasince 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@Betacarriers already lists onlyNodeDefinitionand the PPTX backend — the code disagreed with the policy doc. The marker was also internally inconsistent:inlineSvgIcon/RichText.svgIconand the emoji pipeline were built on@BetaSvgIconwithout carrying the annotation themselves.What changed
SvgIcon,SvgPath(class-level),PathBuilder.svg(svgPath), bothAbstractFlowBuilder.addSvgIcon(...)overloads andShapeContainerBuilder.path(w, h, svgPath)(these three used the fully-qualified@com.demcha.compose.document.api.Betaform — a plain-text@Betagrep misses them), andDocumentPaint.LinearAxis/RadialCircle. The paints graduate together with the reader that emits them:SvgIcon.LayerexposesDocumentPaintpublicly, so a beta paint under a stable icon would re-create the same inconsistency this PR closes.SvgIcon,SvgPath,document.svgpackage-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.### Public APIentry under v2.2.1 — Planned calls the transition out explicitly, as the policy requires, and names the two remaining@Betacarriers (NodeDefinitionExtension SPI, PPTX backend), which now matchdocs/api-stability.mdexactly — no doc edit needed there.BetaAnnotationDocumentationTestpins 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 -am→ BUILD SUCCESS (exit 0, unpiped), and the Javadoc gate./mvnw -B -ntp javadoc:javadoc→ BUILD 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@Betaexclusion 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).