Skip to content

feat(java): prepare Maven Central releases and retain JitPack - #302

Merged
nik13 merged 5 commits into
devfrom
feat/java-maven-central
Oct 31, 2026
Merged

nik13 merged 5 commits into
devfrom
feat/java-maven-central

Conversation

@nik13

@nik13 nik13 commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Prepare the existing Java SDK for Maven Central releases under com.futureagi, with JitPack retained for commit-pinned, unreleased builds. This PR targets dev; it does not merge, tag, or publish a Central release.

  • Migrate Maven coordinates in Java POMs/examples; keep every ai.traceai.* Java package/import unchanged.
  • Add traceai-bom covering all 24 SDK modules. The parent POM remains the SDK version source (1.0.0), including the runtime version resource.
  • Add inherited Central/SCM metadata and a release-only profile for sources, Javadocs, environment-backed GPG signing, and central-publishing-maven-plugin (central, autoPublish=true, waitUntil=published).
  • Remove the hard-coded local Byte Buddy agent path that broke clean-machine test startup.
  • Add Java CI, Central metadata/artifact checks, and independent consumer-compilation regressions.
  • Rework the Java README with Central Maven/Gradle installs first, commit-pinned JitPack as the secondary route, accurate FI_* authentication variables, and the module-derived integration list.
  • Repair the OpenAI example's Optional usage handling and add a single-request smoke mode with optional OpenAI-compatible base URL/model.

Independent-verifier fixes

All three blocking findings are fixed in follow-up commits on this same branch.

P1: JitPack builds must produce installable artifacts, not merely report ok

JitPack could publish a successful build while child POMs referred to an unavailable traceai-java-parent. The opt-in jitpack profile now installs self-contained, flattened POMs without parent references. A JitPack-only post-install hook explicitly maps internal dependencies and BOM dependency management to the exact requested JitPack coordinates; JitPack's own remapping did not handle managed dependencies. Normal and Central release POMs retain com.futureagi and their original parent structure.

JitPack now uses a checksum-verified Maven 3.9.9 wrapper, avoiding image-dependent Maven versions. The harvesting hook supports the legacy image's Python 3.5 syntax and runs only after a successful Maven installation.

Current head f5e5b9045295949416d66e6117cd44b7035520a6 is verified end to end:

  • JitPack build API: ok, all 26 modules.
  • Three independent Maven applications compiled against public JitPack artifacts with a new, empty Maven repository: the actual README OpenAI snippet, the OpenAI-plus-Spring-Boot setup, and a BOM/main-classpath consumer.
  • That repository contains no local com.futureagi artifacts. Public BOM/OpenAI/core/starter/Spring-AI POMs have no parent references, and the public BOM manages all 24 SDK modules at the exact JitPack group and head SHA.

Reproduce from the repository root, with JDK 21 and Maven available:

python3 -I java/scripts/test_consumers.py --jitpack-version f5e5b9045295949416d66e6117cd44b7035520a6

P2: Spring Boot instructions must retain direct OpenAI instrumentation

Both Maven and Gradle instructions now describe the starter as additional, not a replacement for traceai-java-openai. The README's actual Java snippet compiles with both dependencies in an independent Maven application and with the corrected Gradle dependency block. A negative control using only the starter fails with package ai.traceai.openai does not exist, as expected.

P2: Public BOM must not force consumer dependencies into test scope

The parent manages test-library versions only; the reactor's actual dependencies already declare scope=test individually. The public BOM no longer forces OpenTelemetry SDK testing, JUnit, AssertJ, or Mockito into test scope.

An independent application imports the BOM and uses all five managed artifacts in src/main/java, without versions or explicit scope overrides. It compiles with both normal Central-coordinate POMs and public current-head JitPack POMs. The same fixture fails with the previous parent POM's scopes and succeeds after replacing only that parent POM with the fix. Gradle's main-classpath consumer also compiles.

Validation

Heavy local builds ran through the shared build lock, with JDK 21. The final wrapper-based checks use Maven 3.9.9.

  • Final ./mvnw -B -ntp verify: 26 reactor projects successful, 14 tests passed, 109 credential-gated provider E2E tests skipped, no failures/errors.
  • Final ./mvnw -B -ntp -P release -Dgpg.skip package: successful; all 24 binary/source/Javadoc JAR sets built, with Javadoc errors still fatal.
  • Final release-profile effective-POM checker: 26/26 pass required Central metadata, coordinate/version, BOM-coverage, and release-JAR checks. The release profile does not activate the JitPack flatten plugin.
  • All three independent consumers pass with normal installed POMs and locally flattened POMs; CI repeats both paths and validates all 26 flattened POMs plus the managed-dependency remapping step.
  • README Gradle consumer compiles with the additive starter and the five BOM-managed libraries on the main classpath.
  • Final Java workflow passes actionlint; shell syntax and a fresh-cache wrapper download/checksum validation pass locally.
  • Final-head hosted CI: 8 passing checks, 3 path-filtered skips, including the Linux Java reactor, release-artifact, and external-consumer job.
  • Original live smoke validation remains unchanged: a real OpenAI-compatible CLIProxy request was exported to Future AGI Cloud and read back as trace 1883f49e-4920-44c1-2dc6-5fad601956ce, one OK LLM span, model gpt-6.1-sol, tokens 314 / 11 / 325, input/output present. No provider calls were needed for this fix round.

Maintainer prerequisites and limits

  • Before the first actual Central release, verify com.futureagi in the Sonatype Central Portal and configure server central with MAVEN_CENTRAL_USERNAME / MAVEN_CENTRAL_PASSWORD, plus MAVEN_GPG_PRIVATE_KEY / MAVEN_GPG_PASSPHRASE.
  • mvn -B -ntp -P release deploy is a real publish operation, not a dry run. It was not executed. Production signing and a Central upload remain intentionally untested.
  • Credential-gated E2E skips do not establish provider compatibility; only the original OpenAI smoke request was exercised live in this lane.
  • No registry login, settings/secrets changes, tags, GitHub releases, or merges were performed. JitPack commit builds were requested solely to validate the secondary installation route.

Interaction with #204

The separate Spring AI 1.1 compatibility PR #204 overlaps the Java POMs/examples and README. The original read-only merge simulation confirmed a README conflict. When combining these PRs, preserve com.futureagi, the release profile/BOM, and the JitPack-specific preparation, and migrate #204's new compatibility-cell POM coordinates too. This PR deliberately retains the current 1.0.0-M4 Spring AI dependency; its implementation/test changes are not copied here.

🤖 Generated with Claude Code

Use com.futureagi coordinates, add a BOM and release-only Central publishing profile, and verify all Java modules and release artifacts in CI. Keep package imports unchanged and document commit-pinned JitPack installs.

Co-Authored-By: Claude Code <noreply@anthropic.com>
nik13 added a commit that referenced this pull request Oct 29, 2026
Align the deployment environment with the actual release profile in #302; no local GnuPG keyring is needed.

Co-Authored-By: Claude Code <noreply@anthropic.com>
nik13 and others added 4 commits October 29, 2026 07:07
Flatten only JitPack consumer POMs, preserve Central coordinates, remove inherited test scopes from public dependency management, and compile external README, Spring Boot, and BOM consumers in CI.

Co-Authored-By: Claude Code <noreply@anthropic.com>
The first clean public consumer exposed that JitPack remaps direct dependencies but leaves dependencyManagement at Central coordinates. Prepare only installed flattened POMs for harvesting and regress both managed mapping and rejection of normal Central POMs.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Use the checksum-verified Maven 3.9.9 wrapper, chain the harvesting step to successful installation, and keep the small preparation script compatible with Python 3.5 on JitPack legacy images.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Prefer shasum when available because the macOS sha256sum check mode does not accept the GNU stdin syntax. Keep SHA-256 verification mandatory on both paths.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 98bd8be into dev Oct 31, 2026
21 checks passed
@nik13
nik13 deleted the feat/java-maven-central branch October 31, 2026 04:27
nik13 added a commit that referenced this pull request Oct 31, 2026
Resolve java/README.md against the rewritten Java README from #302/#304:
keep dev's README and add this PR's hideErrorDetails option and Privacy
controls section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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