What
The japicmp binary-compatibility gate is declared in core/pom.xml and nowhere else.
No other module's pom.xml mentions it. So it guards exactly one published artifact,
graph-compose-core, against the japicmp.baseline property pinned there (2.0.0).
docs/api-stability.md § Binary-compatibility enforcement states this plainly — the
profile runs "on the engine module", with "the published graph-compose-core on Maven
Central" as the baseline.
But graph-compose-templates, graph-compose-render-pdf, graph-compose-render-docx
and graph-compose-render-pptx are all published to Maven Central too (none sets
maven.deploy.skip), and docs/api-stability.md § 4 declares their packages Stable:
| Package |
Tier |
Module |
com.demcha.compose.document.templates.api |
Stable |
graph-compose-templates |
com.demcha.compose.document.templates.core.* |
Stable |
graph-compose-templates |
com.demcha.compose.document.templates.cv.* |
Stable |
graph-compose-templates |
com.demcha.compose.document.templates.coverletter.* |
Stable |
graph-compose-templates |
com.demcha.compose.document.templates.invoice.* |
Stable |
graph-compose-templates |
com.demcha.compose.document.templates.proposal.* |
Stable |
graph-compose-templates |
com.demcha.compose.document.templates.data.* |
Stable |
graph-compose-templates |
Stable means "major releases only" (§ 1). Nothing enforces that outside core.
Why it matters — this is not hypothetical
While implementing letter spacing, TextOrnaments.spacedUpper(String) — public, in
templates.core.text, no @Beta, no @Internal, therefore Stable by the § 1 default —
was deleted outright. All 11 CI checks passed, japicmp included. A consumer on 2.3.0
calling it would have got a NoSuchMethodError from a 2.4.0 minor.
It was caught by reading docs/api-stability.md during review, not by any gate. The
method has since been restored and deprecated instead, so nothing is broken today —
but the hole that let it through is still open, and the next one may not be read for.
Note also that Stable is the default tier: a class nobody thought to annotate is
Stable. "No annotation" is not evidence that a templates method is free to change.
Suggested shape
Lift the japicmp profile out of core/pom.xml into something the published modules
share (the parent, or a small profile they each activate), with a per-module
japicmp.baseline. Two details that the core setup already got right and a copy should
keep:
- The baseline is the major floor (
2.0.0 for the whole 2.x line), not the previous
release — that is what makes the Stable promise hold across a line rather than only
between neighbours.
@Internal packages are excluded. Each module needs its own exclusion list;
render-pptx/render-docx/render-pdf carry internal backend packages that must not
be gated.
Per docs/api-stability.md (see reference_japicmp_two_baselines discussion in
PR #579) a module may want both a floor and a previous-release execution; whatever is
chosen, assert that the executions actually exist, because a profile that silently
no-ops looks identical to a green gate.
Checking it by hand until then
git diff origin/develop...HEAD -- templates/src/main/java \
| grep -E "^[-+].*\bpublic\b.*\("
A - line is a binary break.
Scope
Not blocking. Deliberately left out of the letter-spacing PR, which restores and
deprecates the method rather than removing it.
What
The
japicmpbinary-compatibility gate is declared incore/pom.xmland nowhere else.No other module's
pom.xmlmentions it. So it guards exactly one published artifact,graph-compose-core, against thejapicmp.baselineproperty pinned there (2.0.0).docs/api-stability.md§ Binary-compatibility enforcement states this plainly — theprofile runs "on the engine module", with "the published
graph-compose-coreon MavenCentral" as the baseline.
But
graph-compose-templates,graph-compose-render-pdf,graph-compose-render-docxand
graph-compose-render-pptxare all published to Maven Central too (none setsmaven.deploy.skip), anddocs/api-stability.md§ 4 declares their packages Stable:com.demcha.compose.document.templates.apigraph-compose-templatescom.demcha.compose.document.templates.core.*graph-compose-templatescom.demcha.compose.document.templates.cv.*graph-compose-templatescom.demcha.compose.document.templates.coverletter.*graph-compose-templatescom.demcha.compose.document.templates.invoice.*graph-compose-templatescom.demcha.compose.document.templates.proposal.*graph-compose-templatescom.demcha.compose.document.templates.data.*graph-compose-templatesStable means "major releases only" (§ 1). Nothing enforces that outside core.
Why it matters — this is not hypothetical
While implementing letter spacing,
TextOrnaments.spacedUpper(String)— public, intemplates.core.text, no@Beta, no@Internal, therefore Stable by the § 1 default —was deleted outright. All 11 CI checks passed, japicmp included. A consumer on 2.3.0
calling it would have got a
NoSuchMethodErrorfrom a 2.4.0 minor.It was caught by reading
docs/api-stability.mdduring review, not by any gate. Themethod has since been restored and deprecated instead, so nothing is broken today —
but the hole that let it through is still open, and the next one may not be read for.
Note also that Stable is the default tier: a class nobody thought to annotate is
Stable. "No annotation" is not evidence that a templates method is free to change.
Suggested shape
Lift the
japicmpprofile out ofcore/pom.xmlinto something the published modulesshare (the parent, or a small profile they each activate), with a per-module
japicmp.baseline. Two details that the core setup already got right and a copy shouldkeep:
2.0.0for the whole 2.x line), not the previousrelease — that is what makes the Stable promise hold across a line rather than only
between neighbours.
@Internalpackages are excluded. Each module needs its own exclusion list;render-pptx/render-docx/render-pdfcarry internal backend packages that must notbe gated.
Per
docs/api-stability.md(seereference_japicmp_two_baselinesdiscussion inPR #579) a module may want both a floor and a previous-release execution; whatever is
chosen, assert that the executions actually exist, because a profile that silently
no-ops looks identical to a green gate.
Checking it by hand until then
A
-line is a binary break.Scope
Not blocking. Deliberately left out of the letter-spacing PR, which restores and
deprecates the method rather than removing it.