Skip to content

release.md

Latest commit

 

History

History
92 lines (70 loc) · 5.03 KB

release.md

File metadata and controls

92 lines (70 loc) · 5.03 KB
Raw

Release lifecycle

This page owns release mechanics. Version and change semantics are defined in ADR-014.

Release flow

The Release workflow runs on main:

  1. release-please maintains a rolling release PR with the root version, changelog, manifest, public guide dependency examples, and homepage current-release line.
  2. Merging that PR creates the v<version> tag and GitHub Release.
  3. The publish job checks out the tag, builds and signs Maven publications, generates SBOMs and provenance attestations, then uploads the bundle to Central for automatic publishing.
  4. After the Maven publish job succeeds, docs-publish calls the shared documentation workflow to package docs/site/ from the software tag as the immutable docs-site.tar.gz release asset and notify jsonapi-docs for assembly, validation, and deployment.

gradle.properties is the version source. Keep the release-managed markers in docs/site/getting-started.md and docs/site/index.md; do not update their release versions independently. These versions advance when the release PR merges, before Central publication is verified; the homepage current-release line is not confirmation of artifact availability.

Release PR review

Release notes must reflect meaningful consumer-visible changes. Keep the PR open as an accumulator; do not merge it for internal-only changes. Merging is the release decision.

Before merging:

  • Check that the version, manifest, changelog, guide dependency examples, and homepage current-release line agree.
  • Review supported API and behavior changes, including dependency support changes, against ADR-014 and the release notes.
  • For Jackson baseline changes, check the documented Jackson 3 support and run the checks below.
  • For 0.3.0, confirm the breaking withdrawal of jsonapi-java-jackson2 and the separately published internal jsonapi-java-mapping artifact is in the release notes, and that neither artifact or dependency appears in staged publications or release SBOMs. Historical 0.2.0 artifacts remain immutable; check the five-artifact inventory against ADR-016 before releasing.
  • Check every public guide Javadoc/class link and source fallback against the proposed release version, not the previously published version. Versioned docs must be tag-ready before merging the release PR; check relative links and assets under /core/<version>/ and leave portal publication to the portal owner.
  • Confirm required PR checks pass.

Publication verification

Check that the publish job succeeded and all release-train artifacts are available on Maven Central under com.kazforge before announcing availability. Verify signed publications, per-module cyclonedx SBOMs, and GitHub provenance/SBOM attestations for the primary JARs. Published artifacts are immutable; corrections require a new train version.

After publication, verify that the already-versioned links in the tagged guide resolve for all five consumer artifacts and that the shared portal publishes the release guide. If javadocs.dev is unavailable, link to source Javadocs pinned to the same tag and label them as source.

The documentation revision workflow calls the same shared publisher for changes confined to docs/site/ on main. It appends docs-site-r<N>.tar.gz assets to the current software release, preserving the original snapshot and earlier revisions. Keep revisions compatible with that released API. The portal selects the highest numeric revision without changing software versions or guide URLs. Do not amend released tags or replace assets.

Portal-root discovery files are maintained by jsonapi-docs, not Core.

Dependency-baseline acceptance

When changing a Jackson minimum or test-version selection, test both selections:

./gradlew clean build
./gradlew :jsonapi-java-jackson3:test -PjacksonTestVersion=current

Generate consumer metadata for Jackson 3:

./gradlew :jsonapi-java-jackson3:generatePomFileForMavenJavaPublication \
  :jsonapi-java-jackson3:generateMetadataFileForMavenJavaPublication

Repeat with -PjacksonTestVersion=current. Compare Jackson 3's build/publications/mavenJava/pom-default.xml and module.json using xmllint and jq. Both selections must publish the documented Jackson minimums with ordinary version declarations: no strict constraints, forced versions, platforms, or version ranges.

Failure and retry

  • Conflicting release PR: resolve in favor of the release-please proposal and re-review the version.
  • Missing tag or GitHub Release after merge: re-run the Release workflow; do not create tags manually.
  • Failed publish job: fix the cause and re-run only that job. Re-running the whole workflow finds the existing release and skips publication.
  • Central validation failure: fix the cause and ship the next train version; never overwrite published artifacts.