Skip to content

docs+chore: README + showcase Maven-Central-only; guard accepts Planned version (Phase 2)#104

Merged
DemchaAV merged 1 commit into
developfrom
chore/cut-release-central-migration
May 31, 2026
Merged

docs+chore: README + showcase Maven-Central-only; guard accepts Planned version (Phase 2)#104
DemchaAV merged 1 commit into
developfrom
chore/cut-release-central-migration

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Summary

Phase 2 of the Maven Central coordinate migration: forward-facing install snippets in `README.md` and `docs/index.html` now show only Maven Central coordinates; the legacy JitPack URL stays alive for v1.6.5-and-earlier pinned consumers but is no longer documented as an install option anywhere.

The chicken-and-egg this PR resolves: the install snippet has to advertise the about-to-ship version (1.6.6) so users who copy it get a coord that resolves once the tag lands, but the library `pom.xml` still carries the previous version (1.6.5) until cut-release runs.

The fix is in `VersionConsistencyGuardTest`: the snippet version must equal either the current `pom.xml` version OR the version named in the top `## v<X.Y.Z> — Planned` CHANGELOG entry. `cut-release.ps1` bumps both to the same target in the release commit, after which the two converge and the looser check continues to pass.

What changes

`README.md`

  • JitPack install section deleted (was both Maven + Gradle blocks, lines 111-128)
  • JitPack `img.shields.io` badge deleted
  • `### Maven Central (primary, from v1.6.6)` section header demoted to plain `## Installation` since Central is the only option now
  • Distribution status note rewritten: Central is canonical, JitPack remains resolvable for legacy pinned consumers but is not a documented install path
  • "Latest stable" status block drops the "(JitPack)" qualifier

`docs/index.html`

`VersionConsistencyGuardTest`

  • `readmeInstallSnippetsMatchTheProjectVersion`: accepts either pom version or CHANGELOG Planned version (set-membership instead of strict equality)
  • `showcaseSiteVersionMatchesTheProjectVersion`: drops the JitPack `downloadUrl` assertion, uses Maven Central regex for the install snippets, also accepts the pom-or-Planned target set
  • Both snippet checks try a Maven Central regex first, fall back to the legacy JitPack regex — handles the snippet during any transition window cleanly
  • Pulls Planned version from CHANGELOG via regex on `^## v(...) — Planned`

`scripts/cut-release.ps1`

  • `Update-ReadmeVersion` bumps Maven Central snippet (lowercase artifactId, bare semver) with a fallback to legacy JitPack regex
  • `Update-IndexHtmlVersion` drops the JitPack downloadUrl regex, adds Central artefact URL regex, switches install-snippet regexes to Maven Central format

Not changed (intentional)

Sample CV data in `ExampleDataFactory.java` and `CvV2VisualParityTest.java` still lists "JitPack" as a fictional skill. That string is fictional CV content (a fake person's listed skill), not a documented coord. Changing it would diff every CV-v2 visual snapshot baseline (16 presets) for a cosmetic gain.

Test plan

  • `./mvnw test -Dtest=CanonicalSurfaceGuardTest,DocumentationExamplesTest,DocumentationCoverageTest,VersionConsistencyGuardTest -pl .` → 30/0/0
  • CI: standard guard suite + JDK 17/21/25 + binary-compat + examples smoke + perf smoke

Stack

Independent from #102 (EngineShowcase) and #103 (Phase 1 non-version-locked docs). All three target `develop`, can land in any order.

After all three merge, the migration is complete — `develop` carries only Maven Central documentation, the install snippet shows the v1.6.6 coord, and `cut-release.ps1` is ready to bump it on tag cut.

…ed version

Phase 2 of the Maven Central coordinate migration. Forward-facing
install snippets in README.md and docs/index.html now show only the
Maven Central coordinates; the legacy JitPack URL stays alive for
v1.6.5-and-earlier pinned consumers but is no longer documented as
an install option anywhere.

The chicken-and-egg this PR resolves: the install snippet has to
advertise the about-to-ship version (1.6.6) so users who copy it
get a coord that resolves once the tag lands, but the library
pom.xml still carries the previous version (1.6.5) until cut-release
runs. The fix is in VersionConsistencyGuardTest: the snippet version
must equal either the current pom.xml version OR the version named
in the top "## v<X.Y.Z> — Planned" CHANGELOG entry. cut-release.ps1
bumps both to the same target in the release commit, after which
the two converge and the looser check continues to pass.

README.md changes:
- JitPack install section deleted (was both Maven + Gradle blocks)
- JitPack img.shields.io badge deleted
- "Maven Central (primary, from v1.6.6)" section header demoted to
  plain "Installation" since Central is the only option now
- Distribution status note rewritten: Central is canonical, JitPack
  remains resolvable for legacy pinned consumers but is not a
  documented install path
- "Latest stable" status block drops the "(JitPack)" qualifier

docs/index.html changes:
- Install section H2 changes from "JitPack, no extra setup." to
  "Maven Central. One dependency."
- Maven install block: drops <repository> block, switches groupId
  to io.github.demchaav, artifactId to lowercase graphcompose,
  version drops the v-prefix (canonical Maven Central form)
- Gradle install block: drops repositories { maven } block, switches
  coord to io.github.demchaav:graphcompose:1.6.6
- JSON-LD downloadUrl switches from
  https://jitpack.io/#DemchaAV/GraphCompose/v1.6.5 to
  https://central.sonatype.com/artifact/io.github.demchaav/graphcompose/1.6.6
- JSON-LD softwareVersion stays bare semver (now 1.6.6)

VersionConsistencyGuardTest changes:
- readmeInstallSnippetsMatchTheProjectVersion accepts either pom
  version or CHANGELOG Planned version (set-membership instead of
  strict equality)
- showcaseSiteVersionMatchesTheProjectVersion drops the JitPack
  downloadUrl assertion (the URL is now Central, not JitPack), uses
  Maven Central regex for the install snippets, also accepts the
  pom-or-Planned target set
- Both snippet checks try a Maven Central regex first, fall back to
  the legacy JitPack regex — handles the snippet during any
  transition window cleanly
- Pulls Planned version from CHANGELOG via regex on
  "^## v(...) — Planned" at the top of the file

scripts/cut-release.ps1 changes:
- Update-ReadmeVersion bumps the Maven Central snippet (lowercase
  artifactId, bare semver) with a fallback to the legacy JitPack
  regex (capital-G artifactId, v-prefixed version) so the script
  remains idempotent if a future docs change re-introduces a
  JitPack snippet
- Update-IndexHtmlVersion drops the JitPack downloadUrl regex,
  adds a Central artefact URL regex, switches install-snippet
  regexes to Maven Central format (lowercase artifactId, bare
  semver, no repository declaration)

Guard suite green: CanonicalSurfaceGuardTest +
DocumentationExamplesTest + DocumentationCoverageTest +
VersionConsistencyGuardTest = 30/0/0.

Note: sample CV data in ExampleDataFactory.java and
CvV2VisualParityTest.java still lists "JitPack" as a fictional
skill. That string is fictional CV content, not a documented coord;
changing it would diff every CV-v2 visual snapshot baseline (16
presets) for a cosmetic gain. Left intentionally unchanged.
@DemchaAV DemchaAV merged commit 49f0aac into develop May 31, 2026
11 checks passed
@DemchaAV DemchaAV deleted the chore/cut-release-central-migration branch May 31, 2026 21:03
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