build(api): add japicmp binary-compatibility gate vs v1.6.5 (E1) (#84)

Tracks the public surface against the last published release on every
pull request so an unintended binary break is caught before merge —
the foundation Track E of the v1.6.6 Maven Central debut depends on.

Changes:

- pom.xml: new `japicmp` profile carrying japicmp-maven-plugin and a
  profile-local JitPack repository (downstream consumers do NOT inherit
  it). Pinned versions in properties: japicmp.version=0.23.1,
  japicmp.baseline=v1.6.5. The plugin binds its cmp goal to the verify
  phase, so `mvn -P japicmp verify` runs the diff after building the jar.
- .github/workflows/ci.yml: new `binary-compat` job, PR-only, runs
  `mvnw -DskipTests -P japicmp verify -pl .` after the guards job and
  uploads the report directory as an artifact.
- CHANGELOG.md: opens a `## v1.6.6 — Planned` entry with a Build
  subsection documenting the gate, its phased policy (binary breaks
  fail the build, source breaks reported only), and the local invocation.

Policy:

- breakBuildOnBinaryIncompatibleModifications=true
- breakBuildOnSourceIncompatibleModifications=false (phased; will tighten)
- onlyModified=true; reports HTML/MD/XML/diff under target/japicmp/

Local verification: `mvnw -P japicmp verify -pl .` against develop
returns `No changes. Semantic versioning suggestion: 0.0.1` — develop
is bit-identical to v1.6.5 at the jar level, as expected fresh after the
release. The next public-surface PR will exercise the gate end-to-end.

Author: DemchaAV

.github/workflows/ci.yml

@@ -118,6 +118,41 @@ jobs:
           path: examples/target/generated-pdfs/**
           if-no-files-found: error
 
+  binary-compat:
+    name: Binary Compatibility (japicmp vs v1.6.5)
+    if: github.event_name == 'pull_request'
+    needs: architecture-and-documentation-guards
+    runs-on: ubuntu-latest
+    env:
+      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Temurin JDK 17
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      - name: Compare public API against baseline
+        # The `japicmp` profile pulls the v1.6.5 jar from JitPack and
+        # diffs it against the freshly-built artifact. Fails the job on
+        # any binary-incompatible modification to the public surface.
+        # Source-incompatible changes are reported only (phased policy).
+        # See Track E1 in the v1.6.5→1.7 readiness taskboard.
+        run: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl .
+
+      - name: Upload japicmp report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: japicmp-report-${{ github.run_id }}
+          path: target/japicmp/**
+          if-no-files-found: ignore
+
   perf-smoke:
     name: Performance Smoke Check
     if: github.event_name == 'pull_request'

CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to GraphCompose are documented here. Versions
 follow semantic versioning; release dates are ISO 8601.
 
+## v1.6.6 — Planned
+
+First Maven Central release. Adds publishable sources/javadoc jars,
+GPG-signed artifacts, a binary-compatibility gate against v1.6.5, and
+the metadata Maven Central requires. Zero breaking changes; users on
+JitPack continue to resolve through the existing coordinates.
+
+### Build
+
+- **Binary-compatibility gate against v1.6.5** (`japicmp` profile,
+  Track E1). The new `binary-compat` CI job builds the artifact on every
+  pull request and diffs it against `com.github.DemchaAV:GraphCompose:v1.6.5`
+  pulled from JitPack. Binary-incompatible modifications to the public
+  surface fail the build; source-incompatible changes are reported only
+  (phased policy, will tighten after the 1.6.6 cut). Run locally with
+  `./mvnw -DskipTests -P japicmp verify -pl .`; HTML/MD/XML reports
+  land in `target/japicmp/`. JitPack repository is scoped to the
+  `japicmp` profile, so downstream consumers do not inherit it.
+
 ## v1.6.5 — 2026-05-30
 
 ### Templates v2

pom.xml

@@ -68,6 +68,10 @@
         <maven.compiler.plugin.version>3.15.0</maven.compiler.plugin.version>
         <maven.javadoc.plugin.version>3.12.0</maven.javadoc.plugin.version>
         <maven.surefire.plugin.version>3.5.5</maven.surefire.plugin.version>
+
+        <!-- Binary compatibility baseline (japicmp profile) -->
+        <japicmp.version>0.23.1</japicmp.version>
+        <japicmp.baseline>v1.6.5</japicmp.baseline>
     </properties>
 
     <dependencyManagement>
@@ -355,4 +359,66 @@
             </plugin>
         </plugins>
     </build>
+
+    <profiles>
+        <!--
+            Binary-compatibility baseline against the last published
+            release. Activated with `-P japicmp`. Resolves the baseline
+            artifact from JitPack (kept profile-local so consumers do
+            NOT inherit a JitPack repository). Fails the build on any
+            binary-incompatible modification to the public surface;
+            source-incompatible changes are reported but do not fail
+            (yet) so the team can phase the policy in. Tracked in the
+            v1.6.6 stabilization (Track E1).
+        -->
+        <profile>
+            <id>japicmp</id>
+            <repositories>
+                <repository>
+                    <id>jitpack.io</id>
+                    <url>https://jitpack.io</url>
+                </repository>
+            </repositories>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>com.github.siom79.japicmp</groupId>
+                        <artifactId>japicmp-maven-plugin</artifactId>
+                        <version>${japicmp.version}</version>
+                        <executions>
+                            <execution>
+                                <id>japicmp-against-baseline</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>cmp</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                        <configuration>
+                            <oldVersion>
+                                <dependency>
+                                    <groupId>com.github.DemchaAV</groupId>
+                                    <artifactId>GraphCompose</artifactId>
+                                    <version>${japicmp.baseline}</version>
+                                </dependency>
+                            </oldVersion>
+                            <newVersion>
+                                <file>
+                                    <path>${project.build.directory}/${project.build.finalName}.jar</path>
+                                </file>
+                            </newVersion>
+                            <parameter>
+                                <onlyModified>true</onlyModified>
+                                <breakBuildOnBinaryIncompatibleModifications>true</breakBuildOnBinaryIncompatibleModifications>
+                                <breakBuildOnSourceIncompatibleModifications>false</breakBuildOnSourceIncompatibleModifications>
+                                <includeSynthetic>false</includeSynthetic>
+                                <reportOnlyFilename>true</reportOnlyFilename>
+                                <skipPomModules>true</skipPomModules>
+                            </parameter>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
 </project>