[3.0] Published Maven surface omits coordinates the README and plugins resolve

[jbachorik]

Summary

Only io.btrace:btrace (the btrace-dist fat JAR) is published to Central, but the README, the Maven plugin, and the Gradle plugin all tell users to resolve coordinates that are never published. Off a released 3.0 artifact set, the documented secondary install/consume flows fail.

Surfaced during the pre-release cross-module review.

Ground truth (verified)

Publisher side — only btrace-dist, btrace-gradle-plugin, btrace-maven-plugin apply maven-publish, and the release pipeline (.github/workflows/release.yml:426) runs only :btrace-dist:publishAllPublicationsToSonatypeRepository. Sole Central artifact: io.btrace:btrace (btrace-dist/build.gradle:886). The two plugins apply maven-publish but no pipeline job publishes them, and they carry no signing (would fail Central).

Consumer side, all resolving unpublished coordinates:

• README.md:145 — jbang io.btrace:btrace-client:<version>
• btrace-maven-plugin FatAgentMojo.java:69-70 — io.btrace:btrace-agent + io.btrace:btrace-boot
• btrace-gradle-plugin BTraceExtensionPlugin.groovy:164-165 — annotationProcessor "io.btrace:btrace-core:${version}"
• README.md:266,373 + several docs — io.btrace:btrace-metrics (no extension module applies maven-publish)

btrace-core, btrace-agent, btrace-boot, btrace-client, btrace-compiler, and all btrace-extensions/* are never published.

The primary supported path (jbang btrace alias / io/btrace/btrace/<v>/btrace-<v>.jar) does work, so the product is installable — these are secondary documented flows.

Fix (decide intended public surface)

Either:

• Publish more: add maven-publish + signing to core/agent/boot (and extensions if the io.btrace:btrace-metrics embed path is meant to work), and publish the two plugins + their marker artifacts in the stage-maven job; or
• Publish less: remove the Maven-repo resolution in FatAgentMojo, remove the external-consumer annotation-processor fallback in the Gradle plugin, and correct the README/docs coordinates to the single io.btrace:btrace artifact.

Note: the README jbang-client line and the io.btrace:btrace-metrics doc references are deliberately left unfixed pending this decision (all other doc-accuracy fixes from the review pass are already applied).

Severity: MAJOR. Owner: build/release team, with doc follow-up.

[jbachorik]

Decision: only the masked io.btrace:btrace artifact is published

The masked JAR bundles client + agent + compiler + core + runtime + boot (btrace-dist/build.gradle:115-117 + classdata masking; manifest Main/Premain/Agent-Class = io.btrace.boot.Loader), so it is fully self-contained. The individual library modules (btrace-core, btrace-agent, btrace-boot, btrace-client, btrace-compiler, btrace-runtime, and the btrace-extensions/*) will not be published.

Remaining work under this decision

A. Repoint consumers from the unpublished modules to io.btrace:btrace:

• btrace-maven-plugin FatAgentMojo — resolves io.btrace:btrace-agent + io.btrace:btrace-boot; should extract the agent/boot classes from io.btrace:btrace instead (the masked JAR already is the fat agent; the mojo's real job is folding the user's extensions in).
• btrace-gradle-plugin BTraceExtensionPlugin.groovy:164-165 — annotationProcessor fallback resolves io.btrace:btrace-core; should resolve io.btrace:btrace.
• README.md jbang line — io.btrace:btrace-client:<version> → io.btrace:btrace:<version> (Main-Class dispatches to the client).
• Docs referencing io.btrace:btrace-metrics as a Maven coordinate — metrics ships inside the distribution's extensions/ dir, not as a Maven artifact; correct the embed/extension instructions accordingly.

B. Separate sub-decision — do the Gradle and Maven plugins ship in 3.0?
Both apply maven-publish, and the Gradle plugin declares a gradlePlugin{} block, but no pipeline job publishes them and neither carries signing. This is independent of the library decision:

• If yes (supported feature): publish + sign the two plugins (Gradle Plugin Portal / Central) in the release pipeline.
• If no: drop them from the release surface and remove the doc references that imply they are installable.

Once B is decided, the README/doc coordinate fixes in A follow from it.

[jbachorik]

Sub-decision B resolved: the Gradle and Maven plugins WILL be published

Both btrace-gradle-plugin and btrace-maven-plugin ship as supported, published 3.0 artifacts. This finalizes the publication surface:

• io.btrace:btrace — the masked engine JAR (only published library artifact).
• io.btrace:btrace-gradle-plugin + its plugin marker — published.
• io.btrace:btrace-maven-plugin — published.
• (plus the batteries-included agent artifact tracked in [3.0] Publish a batteries-included artifact so jbang users get the default extensions #901.)

Consequent work

Publishing config (needs maintainer-held secrets):

• Add signing to btrace-gradle-plugin/build.gradle and btrace-maven-plugin/build.gradle (Central requires signed artifacts; neither is signed today).
• Decide the Gradle-plugin channel: Gradle Plugin Portal (add com.gradle.plugin-publish) vs Maven Central (the existing maven-publish + gradlePlugin{} already emits plugin markers). Wire the chosen one.
• Add publish jobs for both plugins to release.yml (today only :btrace-dist:publishAllPublicationsToSonatypeRepository runs).
• Provide the required credentials as CI secrets: signing GPG key + Central (Sonatype) token, and — if the portal route — the Gradle Plugin Portal API key.

Repoint the plugins off the unpublished module coordinates (from A):

• FatAgentMojo — extract agent/boot from io.btrace:btrace instead of resolving io.btrace:btrace-agent + io.btrace:btrace-boot.
• btrace-gradle-plugin BTraceExtensionPlugin.groovy:164-165 — annotationProcessor fallback → io.btrace:btrace (not io.btrace:btrace-core).

Docs (now unblocked):

• README.md jbang line → io.btrace:btrace:<version>.
• Extension/embed docs referencing io.btrace:btrace-metrics as a Maven coordinate → describe extensions as bundled in the distribution (and the batteries-included artifact, [3.0] Publish a batteries-included artifact so jbang users get the default extensions #901), not resolvable standalone GAVs.