Skip to content

Extend binary compatibility checking to graph-compose-templates #677

Description

@DemchaAV

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions