Still valid, and worth doing — but the literal form (a git tag per stable XWiki version) would be misleading, so here is a proposal for what to tag instead.
Why version-named tags don't work in this repo:* One commit holds every cycle. master's tree simultaneously contains 16/, 17/, 18/ and 18.4/, currently at 16.10.18, 17.10.10, 18.5.0 and 18.4.2. A tag named 18.5.0 would also carry three unrelated cycles, so the name only describes part of the tree.
The same XWiki version corresponds to many image builds. After stable was bumped to 18.5.0, several commits changed the generated Dockerfiles and entrypoint for that cycle without changing the XWiki version (JDBC driver bumps, LibreOffice pinning, entrypoint fixes). Docker Hub rebuilds and republishes xwiki:18.5.0 from those later commits. A tag 18.5.0 pinned at the version-bump commit would therefore point at a tree that Docker Hub no longer serves under that name — the opposite of what is useful for reproducing an image or building a custom one.
Docker Hub tags are mutable while git tags are conventionally immutable, so reusing the same names across the two invites exactly that confusion.
Also worth noting that for currently supported cycles the files are already directly available in master (18.4/postgres-tomcat/ and friends), so tags are not needed to obtain them.
Where tags do add real value:
Retired cycles disappear. When a cycle is dropped from the repo, its docker-compose.yml and Dockerfile vanish from master, and recovering them requires digging through history.
Reachability of the published commits. The library/xwiki file in docker-library/official-images pins each cycle to a raw commit sha, which docker-library fetches from this repo indefinitely. Those commits are currently reachable only via master.
GitHub Releases with generated changelogs, for people who follow the image rather than the repo.
Proposal: tag each submission to docker-library/official-images, not each XWiki version — an annotated tag on the submitted commit, named release-<stable version>-<build number>, e.g. release-18.5.0-3 for the third published build of the set whose stable version was 18.5.0. The prefix keeps it distinguishable from a Docker tag, the build number means the tag never has to move and never misrepresents what was published, and the tag's annotation message carries the full cycle-to-version mapping, so git tag -n99 answers "which repo state produced xwiki:17.10.10?".
The best moment to implement this is together with XDOCKER-18, which automates the Docker image release. That issue introduces a single submitOfficialImage entry point that generates the library/xwiki file and opens the pull request against docker-library/official-images, so it is the natural and only place where a "this is what was published" tag can be created reliably: the tag can be pushed there right after the pull request is successfully opened, reusing the guards that already require a clean and pushed working tree. Implemented at that point it is a small addition with no CI or workflow impact; implemented separately it would mean either a second manual step in the release process or duplicating that logic.
Past releases could optionally be tagged retroactively and accurately, since the git history of library/xwiki in docker-library/official-images records the exact commits published for every past submission.
Vincent Massol on 25/Jul/26 21:35
Still valid, and worth doing — but the literal form \(a git tag per stable XWiki version\) would be misleading, so here is a proposal for what to tag instead.
Why version\-named tags don't work in this repo:* *One commit holds every cycle.* master's tree simultaneously contains {{16/}}, {{17/}}, {{18/}} and {{18.4/}}, currently at 16.10.18, 17.10.10, 18.5.0 and 18.4.2. A tag named {{18.5.0}} would also carry three unrelated cycles, so the name only describes part of the tree. * *The same XWiki version corresponds to many image builds.* After stable was bumped to 18.5.0, several commits changed the generated Dockerfiles and entrypoint for that cycle without changing the XWiki version \(JDBC driver bumps, LibreOffice pinning, entrypoint fixes\). Docker Hub rebuilds and republishes {{xwiki:18.5.0}} from those later commits. A tag {{18.5.0}} pinned at the version\-bump commit would therefore point at a tree that Docker Hub no longer serves under that name — the opposite of what is useful for reproducing an image or building a custom one. * Docker Hub tags are mutable while git tags are conventionally immutable, so reusing the same names across the two invites exactly that confusion.
Also worth noting that for _currently supported_ cycles the files are already directly available in master \({{18.4/postgres\-tomcat/}} and friends\), so tags are not needed to obtain them.
Where tags do add real value:
* *Retired cycles disappear.* When a cycle is dropped from the repo, its {{docker\-compose.yml}} and {{Dockerfile}} vanish from master, and recovering them requires digging through history. * *Reachability of the published commits.* The {{library/xwiki}} file in {{docker\-library/official\-images}} pins each cycle to a raw commit sha, which docker\-library fetches from this repo indefinitely. Those commits are currently reachable only via master. * GitHub Releases with generated changelogs, for people who follow the image rather than the repo.
Proposal: tag each _submission to docker\-library/official\-images_, not each XWiki version — an annotated tag on the submitted commit, named {{release\-<stable version>\-<build number>}}, e.g. {{release\-18.5.0\-3}} for the third published build of the set whose stable version was 18.5.0. The prefix keeps it distinguishable from a Docker tag, the build number means the tag never has to move and never misrepresents what was published, and the tag's annotation message carries the full cycle\-to\-version mapping, so {{git tag \-n99}} answers "which repo state produced {{xwiki:17.10.10}}?".
The best moment to implement this is together with XDOCKER\-18, which automates the Docker image release. That issue introduces a single {{submitOfficialImage}} entry point that generates the {{library/xwiki}} file and opens the pull request against {{docker\-library/official\-images}}, so it is the natural and only place where a "this is what was published" tag can be created reliably: the tag can be pushed there right after the pull request is successfully opened, reusing the guards that already require a clean and pushed working tree. Implemented at that point it is a small addition with no CI or workflow impact; implemented separately it would mean either a second manual step in the release process or duplicating that logic.
Past releases could optionally be tagged retroactively and accurately, since the git history of {{library/xwiki}} in {{docker\-library/official\-images}} records the exact commits published for every past submission.
Vincent Massol on 25/Jul/26 21:35
Still valid, and worth doing — but the literal form \(a git tag per stable XWiki version\) would be misleading, so here is a proposal for what to tag instead.
Why version\-named tags don't work in this repo:
* *One commit holds every cycle.* master's tree simultaneously contains {{16/}}, {{17/}}, {{18/}} and {{18.4/}}, currently at 16.10.18, 17.10.10, 18.5.0 and 18.4.2. A tag named {{18.5.0}} would also carry three unrelated cycles, so the name only describes part of the tree. * *The same XWiki version corresponds to many image builds.* After stable was bumped to 18.5.0, several commits changed the generated Dockerfiles and entrypoint for that cycle without changing the XWiki version \(JDBC driver bumps, LibreOffice pinning, entrypoint fixes\). Docker Hub rebuilds and republishes {{xwiki:18.5.0}} from those later commits. A tag {{18.5.0}} pinned at the version\-bump commit would therefore point at a tree that Docker Hub no longer serves under that name — the opposite of what is useful for reproducing an image or building a custom one. * Docker Hub tags are mutable while git tags are conventionally immutable, so reusing the same names across the two invites exactly that confusion.
Also worth noting that for _currently supported_ cycles the files are already directly available in master \({{18.4/postgres\-tomcat/}} and friends\), so tags are not needed to obtain them.
Where tags do add real value:
* *Retired cycles disappear.* When a cycle is dropped from the repo, its {{docker\-compose.yml}} and {{Dockerfile}} vanish from master, and recovering them requires digging through history. * *Reachability of the published commits.* The {{library/xwiki}} file in {{docker\-library/official\-images}} pins each cycle to a raw commit sha, which docker\-library fetches from this repo indefinitely. Those commits are currently reachable only via master. * GitHub Releases with generated changelogs, for people who follow the image rather than the repo.
Proposal: tag each _submission to docker\-library/official\-images_, not each XWiki version — an annotated tag on the submitted commit, named after the {{release\-<}} prefix, thestable version>\-< and abuild number>}}, e.g. for example {{release\-18.5.0\-3}} for the third published build of the set whose stable version was 18.5.0. The prefix keeps it distinguishable from a Docker tag, the build number means the tag never has to move and never misrepresents what was published, and the tag's annotation message carries the full cycle\-to\-version mapping, so {{git tag \-n99}} answers "which repo state produced {{xwiki:17.10.10}}?".
The best moment to implement this is together with XDOCKER-18, which automates the Docker image release. That issue introduces a single {{submitOfficialImage}} entry point that generates the {{library/xwiki}} file and opens the pull request against {{docker\-library/official\-images}}, so it is the natural ( and really the only) place where a "this is what was published" tag can be created reliably: the tag can be pushed there right after the pull request is successfully opened, reusing the guards that already require a clean and pushed working tree. Implemented at that point it is a small addition with no CI or workflow impact; implemented separately it would mean either a second an extra manual step in the release process or duplicating that logic.
Past releases could optionally be tagged retroactively and accurately, since the git history of {{library/xwiki}} in {{docker\-library/official\-images}} records the exact commits published for every past submission.
This message was sent by Atlassian Jira (v9.3.0#930000-sha1:287aeb6)
If image attachments aren't displayed, see this article.
