XDOCKER-18: Automate updating the stable version

[vmassol]

What

Automates the manual Update Docker Images
release step as Gradle tasks, mirroring the existing updateLibreOffice precedent. Target UX: ./gradlew release does
the pre-push work, then (after a manual review, commit and push) ./gradlew submitOfficialImage opens the upstream
official-images Pull Request. No JIRA issue and no manual sha256 computation are needed anymore.

Jira: XDOCKER-18

This PR regenerates no image. versions.json starts from exactly the values master generates from today, so the
only generated file that changes is .github/workflows/docker-build.yml, which gains versions.json to its path
filters. The scripts under gradle/ are deliberately not in those filters: none of them takes part in the generation,
so a change to one cannot change an image, and building the whole matrix for it would cost 12 jobs for nothing - that
they still configure and generate is what gradlew-check verifies, now on Pull Requests too.

Where the configuration lives now

The version data moves out of build.gradle into a versions.json data file, and the build logic moves into scripts
applied from gradle/, so that the configuration stays separate from the code updating it and the update tasks can
persist it with JsonOutput.

File	Holds
versions.json	Per cycle: role, the XWiki version + sha256, the three JDBC driver versions + sha256, tomcatImageTag, an optional libraryComment. Shared: the LibreOffice version + one sha256 per architecture.
build.gradle	The template expansion (generate, generateWorkflows) and the model it reads.
gradle/helpers.gradle	HTTP, hashing, version comparison and process helpers.
gradle/update-versions.gradle	updateXWiki, updateJDBC, updateLibreOffice.
gradle/run-instances.gradle	smokeTest.
gradle/official-image.gradle	submitOfficialImage, the generation of the library/xwiki file, and the single map defining what each cycle role means (section comment + PR label) against which the model is checked.
gradle/release.gradle	The release umbrella and the ordering the chained tasks need.

The per-cycle JDBC versions replace the shared mysql / mariadb / postgres maps, since each cycle is now updated
from its own POM. The values are unchanged, cycle 16 included.

The tasks

All are runnable on their own and listed by ./gradlew tasks; release chains the ones a release needs.

Task	What it does
updateXWiki	For each cycle, resolves the latest final XWiki version on that cycle's line from XWiki's Maven metadata; for any that changed, downloads the WAR and computes its sha256. Never downgrades a cycle, and never moves one onto the version line another cycle owns.
updateJDBC	For each cycle, reads the three JDBC driver versions from that cycle's own xwiki-platform POM (mysql.version / mariadb.version / pgsql.version); for any that moved forward, downloads the JAR from Maven Central and hashes it.
updateLibreOffice	Resolves the supported (LTS) LibreOffice version and its per-architecture sha256, writing to versions.json and only when the version actually moved. Fails if the sha256 published for the pinned version no longer matches the pinned one.
generate / generateWorkflows	Unchanged, reading the model from versions.json.
smokeTest	For each cycle whose versions the update tasks moved, builds the postgres-tomcat image plus the image of any variant whose JDBC driver moved, boots each one with docker compose as its own compose project on host port 18080, waits until /rest reports the expected XWiki version, then down -v. Dumps the tail of the container logs when an instance never comes up. -Pcycles=18,17, -Pvariants=mysql-tomcat pick what to boot by hand, which is also how a template/ edit gets boot-checked; standalone it boots every cycle.
release	The pre-push umbrella: updateXWiki → updateJDBC → updateLibreOffice → generate → generateWorkflows → smokeTest.
submitOfficialImage	Generates the docker-library library/xwiki file from the model and opens the official-images Pull Request from your GitHub fork (contents API, no clone). -PdryRun generates the file and shows the diff against the published one without opening a PR.

Decisions worth a review

• A POM driver version is a floor, not a target (updateJDBC). A pin ahead of the POM is a deliberate bump made
  after that cycle was released, so applying the POM value literally would silently revert it and rebuild the images
  for nothing. This is not hypothetical: 18.6.0 declares mysql.version 9.7.0 while 18.4.4 and 17.10.12 declare
  26.7.0, the XWIKI-24657 bump having landed on the maintenance branches first. Upgrades still apply, and the ones
  crossing a driver major say so in the log since the release manager reviews the diff. updateXWiki applies the same
  rule to the XWiki version itself: a pin ahead of everything the Maven metadata lists means the metadata lost it (a
  release pulled for being broken, a repository half synced), not that the cycle should be republished backwards.
• A pinned sha256 that stops matching is a supply chain event, not an update (updateLibreOffice). The Document
  Foundation serving different bytes under a version this repository has already published images for is exactly what
  pinning a hash exists to detect, so the task fails and names both hashes per architecture. Adopting the new hash
  would republish every image on bytes nobody looked at, and report "Updated the sha256" while doing it.
• smokeTest builds the image locally and boots it in isolation. It is the release gate, so it is deliberately
  picky about what it boots and about what counts as green:
  • It builds rather than pulls. The generated docker-compose.yml has no build section, only an image: tag,
    and at release time that tag does not exist on DockerHub yet - the official image is only built once the
    submitOfficialImage Pull Request has been merged. Building here also means what boots is the Dockerfile that was
    just regenerated, not a previously published image.
  • With the classic builder (DOCKER_BUILDKIT=0). That is what the Docker Official Images infrastructure and the
    Docker Build workflow use, and the two builders do not accept the same Dockerfiles, so it is the one whose verdict
    counts. A check building differently from both would miss what they reject.
  • Green means XWiki initialized, not that Tomcat is up. It waits on XWiki's REST API reporting the expected
    product version rather than on an HTTP 200.
  • The version is matched between boundaries, not as a substring. One version string can be the prefix of
    another: an instance answering 17.10.12 contains 17.10.1, so a substring check would let the gate go green on
    the wrong image.
  • Each instance is its own compose project (smoketest-<cycle>-<variant>) on port 18080, not the variant
    directory's default project on 8080, so it can neither collide with an instance started by hand nor down -v
    that instance's volumes away.
  • The rewrites that achieve that isolation fail the build when they find nothing to replace. A silent no-op
    there would cause exactly the collision above, which is the one failure this indirection exists to prevent.
  • It tears the project down before starting it as well as after. The finally covers a normal run and a
    cancelled one, but not a killed daemon or a reboot, and a smoke test adopting a stale container would report on
    that one instead of on the image just built.
  • A failed boot reports the tail of the container logs before the teardown takes them away. A bare timeout is
    not something a failed release can be diagnosed from.
• submitOfficialImage refuses to submit something unreachable: uncommitted tracked changes, HEAD not on
  master (that is the branch docker-library fetches from, being on some remote branch is not enough), or a Pull
  Request still open from a previous run for the same version, whose head branch it would otherwise delete. Untracked
  files are deliberately not part of that - a release manager's scratch note has no bearing on whether the commits we
  emit are reachable - and the offending paths are named in the message rather than left to a git status. It
  regenerates the images before that check, so a versions.json pushed without its regenerated directories shows up as
  that dirty tree: nothing else reports it, docker-build.yml going green on the stale - and therefore fine -
  Dockerfiles while the library file would publish tags they do not produce.
• What builds the images is checked upstream, not here. docker-library builds every image on its own Pull Request
  before merging it, and that gate cannot be waived, so this repository does not pre-check the Docker Build workflow
  result before submitting. See the cleanup round below for why the check that used to be here was removed.
• A dry run stops before the guards. They are all about not writing something wrong, and a dry run writes nothing;
  stopping there is also what makes a preview usable at the moment it is reached for - right after ./gradlew release,
  with the regenerated tree not yet committed, which is exactly the state the guards refuse to submit from. A real run
  throws on the first guard that objects.
• A gh api call a guard reads is not allowed to fail. An empty answer there is indistinguishable from a green
  verdict - a rate-limited or unauthenticated gh would read as "no open Pull Request" and take a branch someone is
  still reviewing down with it - so a check that cannot be made is treated as a check that failed.
• GitRepo now names xwiki/xwiki-docker, not xwiki-contrib/docker-xwiki. This is the one line by which the
  generated file differs from the published one. The published URL only resolves through the redirect GitHub kept when
  this repository moved to the xwiki organisation, and that redirect goes away the day anything else is created under
  the old name - taking the official image builds with it. Revert one line if you would rather do this as its own
  upstream Pull Request.
• The build refuses to generate something it could not publish. An unknown role, more or less than one stable
  cycle, or a variant present in build.gradle but not in the library/xwiki generation all fail at configuration
  time. The variant one matters most: such a variant would be generated, committed and built by CI, yet never reach the
  file that publishes it, so its images would simply not exist on DockerHub.
• Two cycles may not sit on the same version line. The tags a cycle contributes are derived from its version, so
  two cycles on one line both claim it - and docker-library rejects a library file declaring a tag twice. updateXWiki
  therefore refuses the bump that would walk into it, keeping the pin and naming the cycle that owns the line. It is
  reachable: the stable cycle resolves to the latest final of its whole major, which is still on the line an
  intermediate LTS owns until the next minor is released.
• External commands go through Groovy's Process API, since Project.exec is gone from Gradle 9. capture is
  for output that gets parsed, stream for the docker commands, whose output is worth watching as it comes.

Testing

• ./gradlew — regenerating produces no git diff, so gradlew-check passes.
• ./gradlew submitOfficialImage -PdryRun — the generated library/xwiki reproduces the currently published file
  byte for byte except the GitCommit lines, which resolve to the real per-cycle last-touching commits, and the
  GitRepo line corrected above. Checked by diffing both with the GitCommit lines normalised away: the GitRepo
  line is the only other difference.
• updateXWiki, updateJDBC, updateLibreOffice — run live against maven.xwiki.org, Maven Central and the Document
  Foundation; all four cycles resolve to what is pinned. The floor rule is load-bearing rather than defensive: run
  today it holds back five drivers the POMs declare lower than the pins — cycle 18 mysql (9.7.0 < 26.7.0) and
  mariadb (3.5.9 < 3.5.10), and all three of cycle 16 (mysql 9.6.0 < 9.7.0, mariadb 3.5.7 < 3.5.10, postgres
  42.7.9 < 42.7.13). Without it, updateJDBC would downgrade those five and rebuild cycles 18 and 16 backwards.
• The per-cycle JDBC values in versions.json were diffed against what master's shared mysql/mariadb/postgres
  maps resolve to, for all four cycles x three drivers: identical, versions and sha256 alike.
• versions.json round-trips byte-identically through JsonSlurper + JsonOutput.prettyPrint, so an update task
  rewrites only the values it changed rather than reformatting the file.
• ./gradlew release --dry-run — task ordering.
• smokeTest end to end: built cycle 18 postgres-tomcat with the classic builder, booted it, /rest reported
  18.6.0 through the boundary match, teardown removed only the smoketest-18-* resources. The failure path was forced
  with a 20s timeout (both containers' logs reported, then torn down), and the stale-instance path by planting a
  running smoketest-18-postgres-tomcat project and watching the next run reclaim it.
• The guards, each triggered on purpose: an unknown role, two stable cycles, a fourth variant missing from
  library/xwiki, an unquoted port in a generated docker-compose.yml, an XWiki version pinned ahead of the metadata,
  and a MySQL-only driver bump on cycle 17 (which then plans 17 (postgres-tomcat, mysql-tomcat)).
• -Pcycles and -Pvariants are validated against the cycles and variants that exist. Both ways of getting them wrong
  were silent: -Pcycles= left an empty list, which every caller reads as "no selection" and therefore as all of
  them - the opposite of narrowing anything down - and -Pvariants=mysql surfaced only later as a missing directory,
  naming a path rather than the property that named it. Checked with an empty value, an unknown cycle (19) and a
  variant typo (mysql); each names the property and lists the available values.
• The compose rewrites: the three targets are present in all 12 generated docker-compose.yml, and docker compose config on a rewritten file reports the project-scoped container names, DB_HOST wired to the renamed database
  container, port 18080, project-scoped network and volumes, and the image tag resolved from .env.
• Every commit of the branch configures and regenerates with no git diff, so gradlew-check passes on each.
• Not executed: the fork / branch / PUT / Pull Request write path of submitOfficialImage against
  docker-library/official-images, since running it opens a real upstream Pull Request. Its read-only plumbing
  (gh auth status, the upstream fetch, the diff, the guards) was exercised live.

Review round (@claude review of the branch)

Six changes, all in the scripts plus README.md; no generated file moves and library/xwiki is unchanged.

• submitOfficialImage regenerates before it checks the tree. The library file is generated from versions.json
  while docker-library builds the Dockerfiles committed at the emitted GitCommit(s), and nothing tied the two
  together: a versions.json committed without its regenerated directories would publish tags the pushed Dockerfiles
  do not produce. gradlew-check would go red on master, but no guard here read it. Depending on
  generate/generateWorkflows turns the drift into a dirty tree, which the existing guard already reports, naming
  the files.
• updateXWiki refuses a bump onto another cycle's version line, keeping the pin and saying which cycle owns the
  line, rather than writing a versions.json that would make both cycles claim the same tags.
• smokeTest also boots what generate rewrote. It picked its cycles from what the update tasks changed, so an
  edit to template/ - the other thing that changes every image - left the set empty. (Superseded by the cleanup
  round below, which drops the mechanism in favour of -Pcycles.)
• The boolean flags are validated like the others. -PdryRun was a bare hasProperty test, so -PdryRun=false
  read as true - asking not to rehearse is what would have started the real submission. It now accepts no value,
  true or false, and rejects anything else by name, as -Pcycles and -Pvariants already did.
• Two comments. One justified itself by an earlier revision of this branch ("the previous split left...") - which
  nobody reading the file later can see - and another carried a transient issue key. Both now state the reason as it
  stands.

Verified after the changes: ./gradlew and ./gradlew tasks still produce no git diff; versions.json still
round-trips byte-identically; submitOfficialImage -PdryRun still reproduces the published library/xwiki with the
GitRepo and GitCommit lines as its only differences; updateXWiki/updateJDBC/updateLibreOffice still run green
and idempotent against the live sources, with no false positive from the new line check on today's versions.json.
Each fix was also triggered on purpose: a versions.json committed without regenerating is reported as a dirty tree
naming the stale files; a cycle resolving onto another's line is refused by name; -PdryRun=false no longer dry-runs
and -PdryRun=maybe is rejected by name.

Bug found by that review round, fixed here

./gradlew then booting cycle 17 by hand: the mysql and mariadb database containers exited (1):

mysql:   ERROR: Can't initialize batch_readline - may be the input source is a directory or a block device.
mariadb: ERROR: Can't read from a directory 'stdin'

template/docker-compose.yml mounted ./init.sql, while generate copies that file to <variant>/mysql/init.sql
(the include is "${db}/*"). Docker creates a directory for a bind mount source that does not exist, and the
database entrypoints then fail to read it as their SQL script. Pre-existing on master, not introduced here:
git log -S puts it at d1e6ca1 (XDOCKER-296), which changed the mount from ./mysql/init.sql to ./init.sql without
moving the file. cd 17/mysql-tomcat && docker compose up fails on master today, in all 8 mysql/mariadb directories.

It blocks this branch specifically, because smokeTestVariants exists to boot the variant whose JDBC driver moved -
the one check that would exercise a MySQL connector crossing a major - and that boot could only ever fail. It went
unnoticed because every smokeTest reported above was run on postgres-tomcat, the one variant that mounts no script.

• Fixed by mounting ./mysql/init.sql / ./mariadb/init.sql, which is what the template said before d1e6ca1. This
  is the only generated-file change in this Pull Request: 8 docker-compose.yml, one line each.
• Guarded so it cannot come back unnoticed: generate now fails when a generated compose file bind mounts a
  relative path that is not a file next to it. Nothing else covers this - the Docker Build workflow builds the image
  rather than running the compose file, and smokeTest boots one variant per cycle by default, so the other two can
  stay broken for as long as nobody starts them by hand. Checking it at generation time covers all 12 variants on every
  ./gradlew, and therefore on every push and Pull Request through Gradlew Check.

Verified: smokeTest -Pcycles=17 -Pvariants=mysql-tomcat,mariadb-tomcat now boots both and /rest reports 17.10.12,
teardown leaving no container or volume behind; the init script genuinely runs, show grants for 'xwiki'@'%' reporting
the global ON *.* privileges that subwiki creation needs; and the guard fails generation on the reverted template,
naming the file and the path.

Second review round (@claude, narrowed to defects that can produce a wrong release artifact or destroy local data)

One finding, fixed here; no behaviour change and no generated file moves.

• build.gradle held a raw NUL byte - the separator between the path and the content in the generated-directory
  snapshots. Git therefore classified the script as binary: git diff --numstat answered -/-, GitHub rendered it
  as "Binary file not shown", and a concurrent edit could only be resolved by taking one whole side rather than by a
  text merge - on the single file holding the generation logic and workflowPathFilters. Fixed by writing the
  separator as a \n escape. (The snapshots themselves are gone as of the cleanup round below.)

Verified in that round, by running rather than by reading:

• ./gradlew at the branch head: no git diff.
• The generated library/xwiki reproduces the currently published file byte for byte with the GitRepo and
  GitCommit lines normalised away - confirmed independently by driving generateLibraryContent and diffing against
  docker-library/official-images@master.
• versions.json round-trips byte-identically through JsonSlurper + JsonOutput.prettyPrint: no key reordering, no
  string-to-number coercion.
• updateXWiki / updateJDBC / updateLibreOffice against the live sources: all no-ops today, matching the "this PR
  regenerates no image" claim. The floor rule holds back the five drivers listed above, and MySQL's calendar-versioning
  jump is ordered correctly for the right reason - Maven Central publishes 26.7.0 on 2026-07-24 against 9.7.0 on
  2026-04-22, so compareVersions keeping the 26.7.0 pin over the POM's 9.7.0 is an upgrade preserved, not a downgrade
  applied.
• GitRepo: xwiki/xwiki-docker is the canonical name, xwiki/docker-xwiki and xwiki-contrib/docker-xwiki both
  answer 301. The correction is right.
• The compose isolation, on a rewritten file through docker compose config: project smoketest-18-mysql-tomcat,
  volumes smoketest-18-mysql-tomcat_{mysql,xwiki}-data, project-scoped network, renamed containers, port 18080, image
  tag resolved from .env. A down -v provably cannot reach a hand-started instance's mysql-tomcat_* volumes. The
  bind mount resolves to a real <variant>/mysql/init.sql, i.e. the fix above holds.
• The destructive-command surface of the new scripts: no prune, no rm, no git reset/clean/checkout -f, no
  unscoped docker compose down; every down -v is -p-scoped.

Cleanup round: what was removed, and the guarantee it did or did not carry

The branch had accumulated machinery whose cost was review surface rather than safety. Asked which parts of gradle/
could go without losing a real guarantee, the answer came to −348 lines (98 insertions, 446 deletions); gradle/
goes 1465 → 1148 lines. Nothing generated moves, and library/xwiki is unchanged.

Removed because they guaranteed nothing:

• runAll / stopAll, with -PbasePort and -Pfresh (≈115 lines). They boot-checked nothing that
  cd <cycle>/<variant> && docker compose up - which is what the documentation already tells users to run - does not
  already do, and nothing in release touched them. smokeTest keeps the port/name isolation they shared.
• The Docker Build workflow check of submitOfficialImage, with -PskipCiCheck (≈112 lines, taking the exitCode
  helper with it). docker-library builds every image on its own Pull Request before merging it, unwaivably, so this
  only duplicated an upstream gate - and its own waiver existed because that workflow fails on transient
  maven.xwiki.org / download.documentfoundation.org downloads often enough that "a release cannot be held hostage
  to it". A guard whose documented usage includes routine bypass is not a guarantee. Roughly half its length was the
  fallback-run and ancestor-containment reasoning for the case where GitHub had not created the run yet, which then
  resolved to a warning and proceeded anyway.
• The -PtargetRepo rehearsal mode (≈40 lines). It was scaffolding for developing the write path, and it left two
  modes to hold in your head through the whole submission flow.
• The generated-directory content snapshots (≈35 lines). They read and string-compared every generated file twice
  on every ./gradlew to serve one case: release run straight after a template/ edit. smokeTest -Pcycles=...
  asks for that directly, and the README and wiki text now say so.
• The fork-sync retry loop and the collected-problems accumulator. The first covered a once-per-machine fork
  creation race; the second let a dry run list every objection, which no longer applies now that a dry run stops
  before the guards.
• The configuration-time duplicate-tag check (≈20 lines). Redundant twice over: updateXWiki already refuses to
  write two cycles onto one version line, and docker-library rejects the file if one ever got through. Worse, it ran
  at configuration time, so a hand-edited versions.json broke plain ./gradlew generate - the very hazard the
  updateXWiki guard was added to avoid. Verified: in that state ./gradlew now succeeds, and updateXWiki still
  refuses the bump by name.
• compareVersions' qualifier tolerance. Its own comment conceded every version it handles is plain numbers.
  A NumberFormatException in front of a release manager at a terminal is the right failure for a version this build
  has no business ordering.

Fixed, in the opposite direction - something that looked like a guard but laundered a red flag:

• updateLibreOffice now fails when the sha256 published for the pinned version no longer matches the pinned one.
  It used to adopt the new hash and log Updated the LibreOffice sha256 of the unchanged version 25.8.7. Different
  bytes served under a version this repository has already published images for is precisely what pinning a hash exists
  to detect; accepting it silently republishes every image on bytes nobody looked at.

Retest of every feature after the removals

Run against the live sources and a live Docker, not read:

• ./gradlew — configures and regenerates with no git diff, so gradlew-check passes.
• ./gradlew tasks — the surface is generate, generateWorkflows, updateXWiki, updateJDBC, updateLibreOffice,
  smokeTest, release, submitOfficialImage. runAll / stopAll are gone, and the removed flags are inert rather
  than fatal (-PbasePort=nonsense -PskipCiCheck -PtargetRepo=bogus -Pfresh configures fine).
• ./gradlew release --dry-run — ordering still updateXWiki → updateJDBC → updateLibreOffice → generate →
  generateWorkflows → smokeTest → release.
• The three update tasks, live: all no-ops today (18.6.0 / 18.4.4 / 17.10.12 / 16.10.18, LibreOffice 25.8.7), the
  floor rule still holding back the same five drivers, and versions.json untouched.
• The bump paths, forced by pinning cycle 16 back to 16.10.17, its postgres driver to 42.7.0 and LibreOffice to
  25.8.6: each moved forward, and the WAR sha256 updateXWiki computed for 16.10.18 matches the reference hash in
  versions.json byte for byte - sha256OfUrl proven end to end, not just exercised. The simplified
  compareVersions is what orders MySQL 26.7.0 over the POM's 9.7.0 here.
• The new sha256 guard, forced by corrupting the pinned amd64 hash: the task fails, names the architecture and both
  hashes, and leaves versions.json unwritten.
• updateXWiki's two guards, forced: a pin ahead of the metadata (16.99.0) is kept with a message, and a cycle
  that would move onto another's version line is refused by name.
• The role guards, forced: an unknown role, two stable cycles and no stable cycle each fail at configuration
  time with the offending value.
• -Pcycles= / -Pcycles=19 / -Pvariants=mysql / -PdryRun=maybe — each rejected by name, listing the available
  values; -PdryRun=false correctly reads as false.
• verifyBindMounts, forced by pointing the template's mysql bind mount at a file that is not generated: fails and
  names the file and the path.
• The compose rewrite guard, forced by changing how template/docker-compose.yml publishes its port: fails with
  the "no longer match what template/docker-compose.yml generates" message before booting anything.
• submitOfficialImage -PdryRun against a deliberately dirty tree: generates the file, shows the diff and skips the
  guards as intended. The result still reproduces the published library/xwiki with GitRepo and the GitCommit
  lines as its only differences, emits no tag twice, and renders all four role section headers.
• smokeTest for real, twice. Cycle 18 postgres-tomcat: built with the classic builder, came up as
  xwiki-smoketest-18-postgres-tomcat-web on port 18080 alongside unrelated containers left untouched, /rest
  reported 18.6.0, torn down. Then the release integration - cycle 16's mysql driver pinned low, updateJDBC smokeTest
  in one invocation - which planned 16 (postgres-tomcat, mysql-tomcat), i.e. the driver bump pulled in that
  database's variant on top of the baseline, and booted both to 16.10.18. No container or volume left behind.
• versions.json, template/ and the generated tree restored and re-verified clean after every forced failure above.

Docs

• README.md gains a "Releasing new versions" section (in this PR), updated for the removals above.
• Not in this PR: the CLAUDE.md update, and the replacement below for the wiki's "Update Docker Images" section.

Proposed replacement for the wiki "Update Docker Images" section

Drops the "Create a JIRA issue" step and the manual sha256 download/compute/paste step, replaces the manual "Test
Docker Image" procedure with the automated smokeTest, and automates the official-images Pull Request.

Update Docker Images

This should be done only for final versions (i.e. ones that include bugfixes).

The version bumps and the DockerHub official-images Pull Request are automated as Gradle tasks. You only review, commit
and push the docker-xwiki change in between.

1. Update and regenerate the XWiki Docker repository. Clone (or update) the repo with a clean working tree, then
   run ./gradlew release. For every supported cycle this resolves the latest final XWiki version (downloading the WAR
   and computing its sha256 when it changed), updates the JDBC drivers from that cycle's own xwiki-platform POM,
   updates the supported LibreOffice version, regenerates all the Dockerfiles/resources and the build workflow, and
   smoke-tests the cycles whose versions moved (builds the postgres-tomcat image with the classic builder, plus that
   of any variant whose JDBC driver moved, boots each and waits until its REST API reports the expected version).
   Docker must be running. Each step is also runnable on its own:
   updateXWiki, updateJDBC, updateLibreOffice, generate, generateWorkflows, smokeTest.
2. Review, commit and push versions.json together with the regenerated directories. To look at an image by hand,
   run docker compose up in its version/variant directory as usual, or
   ./gradlew smokeTest -Pcycles=18 -Pvariants=postgres-tomcat to boot-check a specific one; the old manual "Test
   Docker Image" procedure also remains available for a deeper test.
3. Submit the DockerHub official image PR. Ensure gh is authenticated, then run ./gradlew submitOfficialImage.
   It regenerates the library/xwiki file and opens a PR against docker-library/official-images from your fork,
   aborting if the tree is dirty, if HEAD is not on master, or if a PR from a previous run is still open. Use
   -PdryRun to generate the file and show the diff without opening a PR.

🤖 Generated with Claude Code

[vmassol]

We need to check those. The script is supposed to take the values from our pom (see https://github.com/xwiki/xwiki-docker/pull/92/changes#diff-49a96e7eea8a94af862798a45174e6ac43eb4f8b4bd40759b5da63ba31ec3ef7R53-R56 ).

It probably means they have not been updated properly in the pom.

[vmassol]

Actually it's because we use the versions used in the last release of XWiki for the branch, see https://github.com/xwiki/xwiki-docker/pull/92/changes#diff-49a96e7eea8a94af862798a45174e6ac43eb4f8b4bd40759b5da63ba31ec3ef7R462-R463

That makes sense, since we should be aligned. It just means that these will be updated after we release XWiki, when we release the docker images.

[surli]

So your PR actually contains both changes in the script and changes performed by the script, right? Would feel cleaner to have a separated commit just for those changes

[vmassol]

After rebasing on master this is now moot: the PR no longer carries any generated-file changes. Cycle 16 is back to the exact values master ships, and the per-cycle POM values (9.6.0 / 3.5.7 / 42.7.9 for 16) will be applied automatically by updateJDBC at the next release — which is when the driver versions get refreshed anyway. So the diff is now script + config only, with no mixed generated output.

One reconciliation note: master's XWIKI-24618 bumped postgres to 42.7.13 (ahead of what the cycle POMs declare). I kept that value across the cycles here rather than reverting it, and updateJDBC will realign everything with the POMs at release time.

[tmortagne]

ahead of what the cycle POMs declare

This is not accurate, as can be seen on https://github.com/xwiki/xwiki-platform/blob/master/pom.xml#L122.

[vmassol]

The changes have been reverted so yes it's not accurate, that's the point! :) Both Simon and you asked for no change to the version in the PR, ie to defer its execution till the PR is merged and when it's used to do a release....

RE <pgsql.version>42.7.13</pgsql.version> your change was not removed.

[tmortagne]

The changes have been reverted so yes it's not accurate, that's the point! :)

You are mixing different things.

"Your" last comment was referring to master, so I answered that no, xwiki-docker is not ahead of master (or any other branch).

[vmassol]

Settled after the rebase, in two parts.

The PR carries no generated-file change at all any more: versions.json is seeded with exactly the driver versions and sha256 that master generates from today, so ./gradlew reproduces every */*/Dockerfile byte for byte. Script plus config only.

And updateJDBC no longer downgrades a driver (commit 58f7436). Read literally, each cycle's own POM would have taken cycle 18 back from mysql 26.7.0 / mariadb 3.5.10 to the 9.7.0 / 3.5.9 the released 18.6.0 POM declares, and cycle 16 to 9.6.0 / 3.5.7 / 42.7.9 — i.e. reverting XWIKI-24656 / XWIKI-24657, which were done here after those cycles were released, and rebuilding the images for nothing. The POM value is now a floor rather than an exact target: anything older than what is pinned is reported and skipped, upgrades still apply, and one crossing a driver major says so in the log since the diff gets reviewed before being committed. Running it today is a no-op on every cycle.

[surli]

smokeTest Boot the postgres-tomcat variant of each changed cycle with docker compose, wait for HTTP 200 on :8080, then down -v.

Two things:

1. shouldn't have a bit more check than just the 200 status, e.g. some content check / REST API version check perhaps?
2. it feels like another task that would do the same but starting them on different ports and keeping them up so that we can access manually to perform checks could be useful no?

[vmassol]

@surli both good ideas:

1. Stronger check than HTTP 200 — agreed. I can make smokeTest also hit /rest/ (or /rest/wikis/xwiki) and assert the response carries the expected XWiki version, so we verify XWiki actually initialized rather than just that Tomcat is up.
2. A keep-them-running task — agreed too. I can add a separate runAll task that starts each cycle/variant on distinct ports (8080, 8081, …) and leaves them up for manual inspection, kept separate from smokeTest (which tears down with down -v).

Update: both are now implemented in this PR (commit e30aa1c) — see the follow-up comment below.

[vmassol]

@surli I went ahead and implemented both suggestions in this PR after all (commit e30aa1c) — they turned out small and self-contained:

1. Stronger smoke check. smokeTest no longer just waits for HTTP 200; it now polls /rest and asserts the response carries the expected XWiki version (the root REST resource returns <version>X.Y.Z</version>, served to guests), so we verify XWiki actually initialized rather than that Tomcat is merely up. Factored into a shared waitForXWiki(port, version, timeout) helper.
2. Keep-them-running task. New runAll task starts each selected cycle/variant on its own host port (8080, 8081, …) as an isolated compose project and leaves them up for manual inspection (kept separate from smokeTest, which still tears down with down -v). It rewrites the generated compose on the fly to avoid port/container-name collisions when several run at once. Defaults to every cycle × variant; narrow with -Pcycles=… / -Pvariants=…. A matching stopAll tears them back down.

Verified live: booted a rewritten instance on a non-default port, XWiki reached its renamed DB and /rest reported the right version in ~50s; teardown removed volumes + network cleanly.

[manuelleduc]

This file is starting to get huge. I'm wondering if we shouldn't move each method in its own file?

[vmassol]

Agreed, done in the rebased commit. build.gradle goes from 280 to 141 lines, keeping only the version-model loading and generate/generateWorkflows; everything else moves into scripts applied from gradle/, grouped by area rather than one file per method (a file per method would scatter helpers that are only meaningful together):

• helpers.gradle (114 lines): the HTTP, hashing, version-compare and process helpers shared by the tasks.
• update-versions.gradle (216): updateXWiki, updateJDBC, updateLibreOffice.
• run-instances.gradle (204): smokeTest, runAll, stopAll.
• official-image.gradle (217): the library/xwiki generation and submitOfficialImage.
• release.gradle (36): the release umbrella and the task ordering.

They exchange the model and the helpers through the project's extra properties, bound at configuration time. That last part also fixed a real problem the split surfaced: reading project from inside doLast is deprecated in Gradle 9.7.1 (Invocation of Task.project at execution time … will fail with an error in Gradle 10), so smokeTest, runAll/stopAll and submitOfficialImage would have broken on Gradle 10, mid-release. The build is warning-free now.

Happy to slice it differently if you would rather have another grouping.

[vmassol]

Rebased on master and addressed the outstanding review comment. History is a single squashed commit (force-pushed), since master had moved 8 commits and the file layout changed.

Rebase. Rather than hand-merging the conflicts, the automation is re-applied on top of master's current files, so nothing master gained meanwhile is lost: build.gradle keeps expandTemplates + generateWorkflows (XDOCKER-422, which this branch predated) and release now chains generateWorkflows too; README.md takes master's short version with the maintainer "Releasing new versions" section appended.

No image change. versions.json is seeded with exactly the values master generates from today, so ./gradlew regenerates every version/variant directory with a zero diff. The only generated change is .github/workflows/docker-build.yml, which gains gradle/*.gradle and versions.json in its path filters so CI still triggers on the build logic.

Split of build.gradle (@manuelleduc's comment): 280 -> 141 lines, the rest in scripts applied from gradle/: helpers.gradle (HTTP/hashing/process helpers, 114), update-versions.gradle (207), run-instances.gradle (204), official-image.gradle (217), release.gradle (36).

Gradle 10 fix found while splitting. The tasks read project.hasProperty(...) / project.ext inside doLast, which Gradle 9.7.1 reports as Invocation of Task.project at execution time has been deprecated. This will fail with an error in Gradle 10. Everything is now bound at configuration time, and updateXWiki hands its changed-cycle list to smokeTest through a shared holder instead of an extra property written at execution time. The build is warning-free.

Verified in this round

• ./gradlew -> clean, zero diff on the generated directories; tasks lists all 10 tasks; release --dry-run -> correct ordering.
• updateJDBC run live against nexus.xwiki.org + Maven Central: works, and versions.json round-trips through JsonOutput with value-only diffs (restored afterwards, so this PR carries no version change).
• submitOfficialImage -PdryRun: reproduces the upstream library/xwiki byte for byte except the GitCommit lines.
• smokeTest -Pcycles=18 run for real against Docker (the path never executed before): green in 1m40s, booted 18.6.0 postgres-tomcat, /rest reported 18.6.0, down -v left nothing behind. Worth noting that its first attempt failed on a Docker Hub layer-pull retry storm, i.e. a registry hiccup fails release at that step.
• No line over 120 characters.

updateJDBC no longer downgrades a driver (second commit). Read literally, each cycle's own POM would have taken cycle 18 from mysql 26.7.0 / mariadb 3.5.10 back to the 9.7.0 / 3.5.9 that the released 18.6.0 POM declares, and cycle 16 to 9.6.0 / 3.5.7 / 42.7.9 — silently reverting the bumps made here after those cycles were released (XWIKI-24656, XWIKI-24657) and rebuilding the images for nothing. The POM value is now treated as a floor: anything older than what versions.json pins is reported and skipped, upgrades still apply, and one crossing a driver major says so in the log since the diff is reviewed before being committed. Running it today is a no-op:

Cycle 18: mysql JDBC POM declares 9.7.0, keeping the pinned 26.7.0 which is ahead of it.
Cycle 18: mariadb JDBC POM declares 3.5.9, keeping the pinned 3.5.10 which is ahead of it.
Cycle 18: postgres JDBC already up to date (42.7.13).
...
Cycle 16: mysql JDBC POM declares 9.6.0, keeping the pinned 9.7.0 which is ahead of it.

[vmassol]

@surli @tmortagne @manuelleduc : all comments addressed, please let me know if you're ok to merge and test this for the next release. Thx

[manuelleduc]

LGTM but I let @tmortagne have the last word since he is he RM for 18.7.0 :)

[tmortagne]

Sure, let's try.