Repository navigation
Extend binary compatibility checking to graph-compose-templates #677
Description
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.0for 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. @Internalpackages are excluded. Each module needs its own exclusion list;
render-pptx/render-docx/render-pdfcarry 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.
Activity
feat(templates): deprecate spacedUpper instead of deleting it
feat(api): add native letter spacing without changing the text layer (#…