Skip to content

ci: open the Javadoc jar before publishing it - #512

Merged
DemchaAV merged 1 commit into
developfrom
ci/wrapper-javadoc-artefact
Aug 4, 2026
Merged

ci: open the Javadoc jar before publishing it#512
DemchaAV merged 1 commit into
developfrom
ci/wrapper-javadoc-artefact

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Aug 4, 2026

Copy link
Copy Markdown
Owner

Why

This is the last open item from the #493/#494 review follow-up, and the one the static
gate cannot cover.

graph-compose — the drop-in coordinate the README sends people to — carries no sources
of its own. Its javadoc jar is built with includeDependencySources, and when that finds
nothing the goal logs "No Javadoc in project. Archive not created", attaches nothing,
and reports BUILD SUCCESS. Every 2.x release shipped an artefact with no pages, and
javadoc.io went on serving 1.9.1 — the newest version that carried an API reference at
all. Nothing was red, because linting sources and producing an artefact are different
things.

PublishedJavadocCoordinateGuardTest guards the configuration. Nothing guarded the output.

What

One CI step, baseline JDK only: build the jar the release profile builds, then open it and
require index.html, GraphCompose.html and DocumentSession.html — what a reader lands
on, what every snippet starts from, and the type they spend the rest of their time in.

It runs three passes, mirroring the order publish.yml deploys in, and the order is the
finding
:

  1. install -pl :graph-compose -am profile-free — every module, including the engine's
    tests jar that render-pdf needs at test scope.
  2. install -pl :graph-compose-core -Prelease — adds the engine's sources jar, which
    includeDependencySources reads. It is release-profile-only, and release also sets
    the tests jar to phase none, which is why this cannot be one pass.
  3. package -pl :graph-compose -Prelease — the wrapper's javadoc jar.

publish.yml gets there for free by deploying the engine before the wrapper, so the
released artefact is fine; this reproduces that ordering rather than assuming it.

Tests

./mvnw -B -ntp clean verifyBUILD SUCCESS; the CI guards pass and the workflow parses.

The first two attempts failed on CI, and both failures were worth having. The first
activated release across -am and broke render-pdf's test-scope resolution. The
second dropped the profile from the dependency pass and produced no jar at all — which
is exactly the bug this step exists to catch, arriving on the step that catches it.

The second one passed locally for the wrong reason: my ~/.m2 held the engine's sources
jar from earlier release builds, and wrapper/target held a stale apidocs the jar goal
archived. Deleting both reproduced the CI failure on this machine — "No Javadoc in
project", BUILD SUCCESS, no artefact — and the three-pass sequence then produced a
1024-entry jar with all three pages from clean.

Also checked from the other side: a probe jar carrying a manifest and one unrelated page
is reported missing on all three and exits 1, and the absent-jar case now carries its own
message instead of a bare ls failure.

The current artefact is healthy — the fix from #492/#494 works. This is the gate that
keeps it that way.

@DemchaAV
DemchaAV force-pushed the ci/wrapper-javadoc-artefact branch from f3682bd to e52f823 Compare August 4, 2026 22:06
The existing Javadoc step lints the engine's sources. It cannot see whether the
artefact Maven Central serves has anything in it, and that is the failure that
happened: graph-compose carries no sources of its own, so the javadoc goal found
nothing to archive and attached a jar with no pages. Every 2.x release shipped
that way, javadoc.io kept rendering 1.9.1 because it was the newest version that
carried a reference at all, and nothing in the build was red.

PublishedJavadocCoordinateGuardTest guards the configuration. This guards the
output: build the jar the release profile builds, then look inside it. Three
pages stand in for the reference — the index a reader lands on, the entry point
every snippet starts from, and the type they spend the rest of their time in.

Checked from both sides rather than trusted because it passed: against the real
jar all three are found, and against a probe jar carrying a manifest and one
unrelated page the step reports each as missing and exits 1.
@DemchaAV
DemchaAV force-pushed the ci/wrapper-javadoc-artefact branch from e52f823 to f99b45b Compare August 4, 2026 22:14
@DemchaAV
DemchaAV merged commit a2a3e14 into develop Aug 4, 2026
12 checks passed
@DemchaAV
DemchaAV deleted the ci/wrapper-javadoc-artefact branch August 4, 2026 22:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant