Fix Maven Central publishing and version artifacts as <semver>-<date>

[handstandsam]

Fixes #226.

After this PR: pushing a vYYYY.MM.DD tag publishes every library module and the trailblaze-android-gradle plugin to Maven Central as 0.1.0-YYYY.MM.DD, fully automatically. Merges to main keep publishing 0.1.0-SNAPSHOT to the Central snapshot repository, unchanged. Today the last consumable release is 0.0.2 (July 2025) and the Gradle plugin has never been published, despite every release run since reporting success.

Why nothing landed since 0.0.2

Three independent defects:

1. Deployments uploaded but never published. publishToMavenCentral() defaults to automaticRelease = false: under the Central Portal API the deployment uploads as USER_MANAGED and waits for a manual Publish click in the portal — while Gradle prints BUILD SUCCESSFUL. (The v2026.08.07 job log ends with Skipping deployment validation!, emitted from inside that upload block.) Now automaticRelease = true, and the default validateDeployment = true blocks the job until Central reaches a terminal state — a rejected deployment turns the job red instead of green-but-published-nothing.

2. The Gradle plugin was never in the release task graph. The aggregator delegating into the composite-included trailblaze-android-gradle build hung off tasks.matching { name == "publishAllPublicationsToMavenCentralRepository" } in the root project, which applies no publish plugin — that container is empty, so nothing ever depended on the aggregator. Registering the delegating task under that name (plus vanniktech's publishToMavenCentral / publishAndReleaseToMavenCentral aliases) is what makes the release command reach the included build.

3. The included build would have released its own SNAPSHOT default. It reads its own gradle.properties and never sees the root's git-tag version override. The workflow now passes -Pversion explicitly, which propagates into the composite (verified with an init-script probe across all three builds), putting the plugin on the same coordinate as the libraries.

Versioning: <semver base>-<tag date>

The tag stays vYYYY.MM.DD, but the Maven coordinate is not the bare tag. 2026.08.11 sorts above any future 1.0.0 in both Gradle's conflict resolution and Maven's ComparableVersion (2026 beats 1 on the first numeric component), so one bare-CalVer release would permanently foreclose a stable semver line — Maven coordinates have no epoch escape hatch. Only 0.0.1/0.0.2 exist on Central, so the door is still open; this PR is what keeps it open.

The version is <semver base from gradle.properties>-<date from the tag>, e.g. 0.1.0-2026.08.14:

• the base carries the API-compatibility signal and is bumped by hand (in both gradle.properties files, root and plugin) only when the contract moves — it is not bumped per release;
• the date records when the build was cut.

Ordering verified against both Gradle 8.14's real conflict resolution and Maven's ComparableVersion — they agree on every case:

A	B	winner
0.0.2 (current Central max)	0.1.0-2026.08.14	the new release
0.1.0-2026.08.11	0.1.0-2026.09.01	later date
0.1.0-2026.08.11	0.2.0-2026.08.01	higher base — base dominates date
0.9.0-2026.12.01	1.0.0	1.0.0 — graduating to a bare stable release works
1.0.0	2026.08.11	2026.08.11 — the trap this scheme avoids

One rule the shape imposes, documented at the derivation site: a dated build of the same base outranks the bare version (1.0.0-2026.11.01 > 1.0.0), so never ship dated builds of a version you intend to release bare — numbered -rc.N qualifiers (1.0.0-rc.1) sort below the final in both tools, and the dot keeps rc.10 above rc.2.

Guardrails: bare CalVer can never ship

Nothing structurally prevented the mistake: gradle/git-version.gradle.kts sets version = 2026.08.14 on any build whose HEAD carries a v* tag — exactly the state a release runs in — so one workflow line was the only defense. Now:

• gradle/maven-version-guard.gradle.kts hard-fails any Maven-Central publish whose version's leading component is a calendar year, hooked into prepareMavenCentralPublishing (before anything is staged, signed, or uploaded) and every PublishToMavenRepository as backstop. It splits on ., -, and _ — Gradle and Maven treat all three as part separators, so 2026-08-11 is as poisonous as 2026.08.11. Applied by the root build and (separately — the root's apply() can't reach a composite build) by trailblaze-android-gradle. Ordinary builds, publishToMavenLocal, and SNAPSHOT publishing are untouched.
• Tag triggers tightened to v[0-9]* (release + build-desktop; ** previously matched backup/… tags), and release.yml asserts the full vYYYY.MM.DD[.N] shape plus a strict <major>.<minor>.<patch> base — with automaticRelease there is no portal gate left, so a stray vendor-x tag would otherwise ship immutable 0.1.0-endor-x clutter to Central. The base check also catches a duplicated version= line.
• No tag-derived text is interpolated into the publish script: the computed version reaches Gradle via env: rather than ${{ }} inside the run: that holds the publish secrets, and the workflow declares permissions: contents: read.

Docs

docs/android_on_device.md now names the trailblaze-android coordinate (nothing in the docs ever did), including the androidx.test:runner line that is not part of the published graph, and explains the version format. The plugin README links its Central artifact.

Verification

• Release-command --dry-run before/after: the included build was absent from the graph before, present after, alongside all 14 subproject publish tasks.
• -Pversion and ORG_GRADLE_PROJECT_* propagation into all three composite builds probed directly.
• Version-ordering matrix run against both Gradle and Maven (table above).
• Guard exercised live in both builds: 2026.08.11 and 2026-08-11 blocked before any staging; 0.1.0-2026.08.11 passes through to the real upload; SNAPSHOT unaffected.
• Merge-then-tag race checked: the snapshot job's checkout (depth 1, no tags) cannot see a release tag, so it can never build at the CalVer version — and the guard would block it anyway.
• ./gradlew -p trailblaze-android-gradle publishToMavenLocal produces jar, sources jar, .module, POM, and the xyz.block.trailblaze.android-gradle.gradle.plugin marker POM.
• mkdocs build --strict passes. No javadoc-jar risk: 0.0.2 published sources-only under the same JavadocJar.None() config.
• Adversarially reviewed (Gradle semantics + CI flow); all findings fixed and folded in above.

Operational notes

• A release creates two Portal deployments (the main build and the included build each run their own build service) that upload and publish independently — a half-red release is possible and would be visible as a failed job.
• The Portal account holds a backlog of unpublished USER_MANAGED deployments, one per tag since the Portal migration, each at a bare CalVer version. They are invisible to consumers and block nothing — but whoever has portal access should drop them (not publish: publishing any one of them springs the CalVer trap permanently).
• --dry-run does not extend into the included build — delegated tasks execute for real. Don't sanity-check the publish aggregators locally with credentials exported (now warned in a comment at the aggregator).