ci: build the engine without the fonts artifact; install fonts for consumer jobs

DemchaAV · DemchaAV · commit c6b920103470 · 2026-06-18T09:30:08.000+01:00
Why: the bundled-fonts split made every engine CI build red. The engine
declared a TEST-scope dependency on io.github.demchaav:graph-compose-fonts,
which is not on Central yet — and Maven resolves declared dependencies before
running (or skipping) tests, so even -DskipTests jobs (japicmp, CodeQL) failed
at "Could not resolve dependencies … graph-compose-fonts:jar:1.0.0 (test)".

What:
- The engine no longer depends on the fonts artifact at all. Its visual /
  snapshot suite gets the bundled fonts on the TEST classpath directly from the
  sibling module's source via a &lt;testResources&gt; entry pointing at
  fonts/src/main/resources. This fully decouples the engine build from the fonts
  artifact: an engine-only build needs no fonts jar published or installed, and
  contributors no longer need a bootstrap install. The fonts are excluded from
  the tests-jar so they don't bloat it (the benchmarks module gets fonts from
  the artifact). The engine pom drops the now-unused graphcompose.fonts.version
  property.
- VersionConsistencyGuardTest now checks the fonts version agrees between the
  aggregator and the bundle (the two modules that pin the artifact); the engine
  no longer carries the property.
- Consumer CI jobs that build the examples / benchmarks modules (which DO depend
  on the fonts artifact) install graph-compose-fonts into the local repo first
  (ci.yml examples / perf-smoke / weekly-diff, benchmarks-jmh.yml). The
  now-unnecessary fonts bootstrap is removed from publish.yml.
- release-process.md §2.D updated to match (no engine fonts.version; no engine
  bootstrap).

Verification: with graph-compose-fonts removed from the local ~/.m2,
./mvnw clean verify -pl . is green (1398 tests) — replicating the CI
environment; the main jar stays 2.54 MB with no fonts/google entries and the
tests-jar carries the test classes but no fonts.
diff --git a/.github/workflows/benchmarks-jmh.yml b/.github/workflows/benchmarks-jmh.yml
@@ -41,6 +41,9 @@ jobs:
           java-version: '17'
           cache: maven
 
+      - name: Install graph-compose-fonts (the benchmarks render with the bundled families)
+        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
+
       - name: Install root artifact (graph-compose + test-jar)
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -99,6 +99,12 @@ jobs:
           java-version: '17'
           cache: maven
 
+      - name: Install graph-compose-fonts (consumed by the examples / benchmarks modules)
+        # The engine itself does not depend on the fonts artifact, but the
+        # examples and benchmarks modules render with the bundled families, so
+        # install graph-compose-fonts into the local repo before building them.
+        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
+
       - name: Install root artifact
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
@@ -202,6 +208,12 @@ jobs:
           java-version: '17'
           cache: maven
 
+      - name: Install graph-compose-fonts (consumed by the examples / benchmarks modules)
+        # The engine itself does not depend on the fonts artifact, but the
+        # examples and benchmarks modules render with the bundled families, so
+        # install graph-compose-fonts into the local repo before building them.
+        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
+
       - name: Install root artifact
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
@@ -264,6 +276,12 @@ jobs:
             benchmark-current-speed-${{ github.ref_name }}-
             benchmark-current-speed-
 
+      - name: Install graph-compose-fonts (consumed by the examples / benchmarks modules)
+        # The engine itself does not depend on the fonts artifact, but the
+        # examples and benchmarks modules render with the bundled families, so
+        # install graph-compose-fonts into the local repo before building them.
+        run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
+
       - name: Install root artifact
         run: ./mvnw -B -ntp -DskipTests install -pl .
 
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -79,14 +79,6 @@ jobs:
           gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }}
           gpg-passphrase: MAVEN_GPG_PASSPHRASE
 
-      - name: Install graph-compose-fonts into the local repo
-        # The engine's visual / snapshot suite renders with the bundled
-        # Google fonts, which now live in the separately-versioned
-        # graph-compose-fonts artifact (engine depends on it at test
-        # scope). Build + install it locally so the verify step below can
-        # resolve it even before it (or this engine version) is on Central.
-        run: ./mvnw -B -ntp -f fonts/pom.xml clean install
-
       - name: Verify (full canonical suite green at tagged commit)
         # Re-verify the tagged commit before publishing — defence in
         # depth against a tag pushed from a broken branch by mistake.
diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md
@@ -121,14 +121,16 @@ is a convenience aggregate `io.github.demchaav:graph-compose-bundle` (under
   `<version>`, push a `fonts-vX.Y.Z` tag. That tag triggers
   [`publish-fonts.yml`](../../.github/workflows/publish-fonts.yml), which deploys
   only `graph-compose-fonts` to Central. Then bump
-  `<graphcompose.fonts.version>` in the engine `pom.xml`, `aggregator/pom.xml`,
-  and `bundle/pom.xml` to the new fonts version so the next engine release pins
-  it (the engine→fonts dependency is test-scope; examples/benchmarks/bundle pin
-  it for real).
-- **First-time bootstrap.** The engine verify depends on `graph-compose-fonts`
-  at test scope. `publish.yml` installs it locally first
-  (`./mvnw -f fonts/pom.xml install`); for a local full-reactor build run that
-  once before building the engine standalone (`./mvnw clean verify -pl .`).
+  `<graphcompose.fonts.version>` in `aggregator/pom.xml` (inherited by
+  examples + benchmarks) and `bundle/pom.xml` to the new fonts version so those
+  consumers pin it. The engine `pom.xml` does **not** carry this property — the
+  engine has no dependency on the fonts artifact (its tests read the fonts from
+  the sibling module's source via `<testResources>`).
+- **No fonts bootstrap for the engine.** Because the engine does not depend on
+  the fonts artifact, `./mvnw clean verify -pl .` builds standalone without the
+  fonts jar being published or installed. Only the consumer modules (examples,
+  benchmarks) need `graph-compose-fonts` in the local repo — their CI jobs run
+  `./mvnw -f fonts/pom.xml install` before building.
 
 ---
 
diff --git a/pom.xml b/pom.xml
@@ -62,20 +62,6 @@
         <mockito.version>5.23.0</mockito.version>
         <byteBuddy.version>1.18.10</byteBuddy.version>
 
-        <!--
-            Bundled Google fonts moved to the independently-versioned
-            io.github.demchaav:graph-compose-fonts artifact in v1.8.0 so an
-            engine upgrade never re-ships ~18 MB of fonts. The engine depends
-            on it at TEST scope only (the visual / snapshot suite renders with
-            the bundled families); it never propagates to consumers, who add
-            graph-compose-fonts (or graph-compose-bundle) themselves. Its
-            version is an independent line — do NOT fold it into the engine
-            lockstep `versions:set`. Keep in lockstep with the same property in
-            aggregator/pom.xml and bundle/pom.xml (no shared parent to
-            single-source it; VersionConsistencyGuardTest enforces agreement).
-        -->
-        <graphcompose.fonts.version>1.0.0</graphcompose.fonts.version>
-
         <!-- Build plugins -->
         <central.publishing.plugin.version>0.10.0</central.publishing.plugin.version>
         <maven.compiler.plugin.version>3.15.0</maven.compiler.plugin.version>
@@ -232,19 +218,15 @@
 
         <!-- Test dependencies -->
         <!--
-            The bundled Google font binaries (graph-compose-fonts) are no
-            longer part of the main artifact. The engine's visual / snapshot
-            suite still renders with them, so they are pulled at test scope.
-            Test scope is deliberate: it keeps fonts off the consumer-facing
-            classpath, so upgrading the engine never drags fonts along.
+            The bundled Google fonts (graph-compose-fonts) are NOT a dependency
+            of the engine — not even at test scope. The engine's visual /
+            snapshot suite renders with them, but they are placed on the TEST
+            classpath directly from the sibling module's source via the
+            <testResources> entry in <build> below. This keeps the engine fully
+            decoupled from the fonts ARTIFACT (no Maven coordinate to resolve, so
+            an engine-only build never needs the fonts jar published or installed
+            first), while still exercising the real font binaries.
         -->
-        <dependency>
-            <groupId>io.github.demchaav</groupId>
-            <artifactId>graph-compose-fonts</artifactId>
-            <version>${graphcompose.fonts.version}</version>
-            <scope>test</scope>
-        </dependency>
-
         <dependency>
             <groupId>ch.qos.logback</groupId>
             <artifactId>logback-classic</artifactId>
@@ -311,6 +293,26 @@
     </dependencies>
 
     <build>
+        <testResources>
+            <!-- Default test resources. -->
+            <testResource>
+                <directory>src/test/resources</directory>
+            </testResource>
+            <!--
+                Bundled Google fonts live in the sibling graph-compose-fonts
+                module since v1.8.0. The engine's visual / snapshot suite renders
+                with them, so put that module's resources on the TEST classpath
+                directly from source. This decouples the engine build from the
+                fonts ARTIFACT (no Maven dependency to resolve, so no CI/local
+                bootstrap is needed) while still exercising the real binaries.
+                Test-only: it never reaches the main jar (built from
+                src/main/resources) and is excluded from the tests-jar below.
+            -->
+            <testResource>
+                <directory>${project.basedir}/fonts/src/main/resources</directory>
+            </testResource>
+        </testResources>
+
         <!--
             Pin the default-lifecycle plugins (clean / install / site /
             resources / deploy) so requirePluginVersions in the enforcer
@@ -445,6 +447,18 @@
                         <goals>
                             <goal>test-jar</goal>
                         </goals>
+                        <configuration>
+                            <!--
+                                The bundled fonts are on the test classpath via
+                                <testResources> for the engine's own suite; keep
+                                them OUT of the tests-jar. The benchmarks module
+                                (the only consumer of this jar) gets fonts from
+                                the graph-compose-fonts artifact instead.
+                            -->
+                            <excludes>
+                                <exclude>fonts/**</exclude>
+                            </excludes>
+                        </configuration>
                     </execution>
                 </executions>
             </plugin>
diff --git a/src/test/java/com/demcha/documentation/VersionConsistencyGuardTest.java b/src/test/java/com/demcha/documentation/VersionConsistencyGuardTest.java
@@ -70,19 +70,18 @@ void everyModuleResolvesToTheRootProjectVersion() throws Exception {
 
     @Test
     void bundledFontsVersionAgreesAcrossModules() throws Exception {
-        // graph-compose-fonts carries an independent version line, but the
-        // ${graphcompose.fonts.version} property that pins it is duplicated in
-        // three poms (engine, aggregator, bundle) because there is no shared
-        // parent to single-source it. This guards the PR-7.1 drift class: the
-        // three must always agree, even though they differ from the engine line.
-        String engine = fontsVersionProperty(PROJECT_ROOT.resolve("pom.xml"));
+        // graph-compose-fonts carries an independent version line. The engine
+        // does NOT depend on the fonts artifact (its tests read the fonts from
+        // the sibling module's source), so the ${graphcompose.fonts.version}
+        // property that pins the artifact lives only in the modules that consume
+        // it: the aggregator (inherited by examples + benchmarks) and the bundle.
+        // This guards the PR-7.1 drift class: those must always agree, even
+        // though they differ from the engine version line.
+        String aggregator = fontsVersionProperty(PROJECT_ROOT.resolve("aggregator/pom.xml"));
 
-        assertThat(fontsVersionProperty(PROJECT_ROOT.resolve("aggregator/pom.xml")))
-                .describedAs("aggregator graphcompose.fonts.version must match the engine's (%s)", engine)
-                .isEqualTo(engine);
         assertThat(fontsVersionProperty(PROJECT_ROOT.resolve("bundle/pom.xml")))
-                .describedAs("bundle graphcompose.fonts.version must match the engine's (%s)", engine)
-                .isEqualTo(engine);
+                .describedAs("bundle graphcompose.fonts.version must match the aggregator's (%s)", aggregator)
+                .isEqualTo(aggregator);
     }
 
     @Test
