Adapt the npm dist-tag of each xwiki-platform release

Development
1

Hello everyone,

Every xwiki-platform release publishes the 66 packages of xwiki-platform-node on npmjs.com. Each release overwrites the latest dist-tag, whatever version it is. latest is what npm install of any package resolves to. So without an explicit version, the most recently published version get installer, regardless of the branch

Current state

The latest version have been

Date Release
2026-09-29 18.8.0
2026-09-30 18.4.6
2026-10-15 18.4.7
2026-10-19 18.9.0-rc-1

So as explain before latest can move to LTS and RC versions somewhat randomly.

Proposal

I propose moving to a dynamic computation of the dist-tag based on the released version.
I’m aiming for a mechanism that need no input from the release manager.
Also note that any package publication requires a dist-tag, so we need to come up with a name for each case.

Published version Dist-tag
Release candidate (e.g., 18.10.0-rc-1) rc
Final release higher than every final release of the package already on npm (e.g., 18.9.1 before 18.10.0 is released) latest
Final release of a package that has never been published (e.g., 18.10.0) latest
Any other final release (e.g., 18.4.8)` stable-X.Y.x (e.g., stable-18.4.x)

Consumers can then install:

  • npm install @xwiki/platform-api: the highest final release.
  • npm install @xwiki/platform-api@rc: the latest release candidate.
  • npm install @xwiki/platform-api@~18.4.0: the latest bugfix release of 18.4

Technical details

  • Latest is resolved by looking registry.npmjs.org, not with the current latest, we use the first existing package we find to resolve the dist-tag of all the packages released together
  • The publication fails if registry.npmjs.org can’t be queried.
  • I don’t plan to have a mechanism to manually force the dist-tag
  • While it’s possible, I don’t plan to support having several dist-tag for a single version
  • The work will need to be backported on 18.4.x (version before 18.0 don’t publish packages and are not in the scope)
  • I don’t plan to manually fix currently inconsistent dist-tag as the next release of a stable version will fix the issue and no one actually complained so far

Excluded options

Configuring the tag in each branch

We could have a constant defined in each branch (e.g., latest, lts,…) but:

  • It’s more maintenance
  • It does not work for a 18.9.1 version released before 18.10.0 is released (i.e., must be latest)

Matching what Debian and Docker does

Our Debian repository offers stable, lts and lts-latest channels. Our Docker images get stable, latest and lts tags from the role each cycle declares in versions.json.
It is more maintenance work as mentioned above, and npm already provide semver ranges already (e.g., ^18.0.0, ~18.4.0, ~17.10.0) so I don’t think this is needed

Conclusion

Here’s my +1.

Thanks

PS: XWIKI-24828: npm packages are published with the latest dist-tag even when released from a maintenance branch by manuelleduc · Pull Request #6337 · xwiki/xwiki-platform · GitHub is a draft PR for this proposal but is currently not aligned with what I propose here

2

I’m globally ok with the proposal but I’m not sure to understand that example:

shouldn’t it use the stable-18.4.x dist-tag you presented in the table above?

3

+1, thank you! As we never agreed how to name the different LTS versions in Docker (as we cannot use latest in any label, we cannot re-use what we use for Debian) I think that’s the simplest solution that also works with any number of maintained branches.

From what I understand it doesn’t need our dist-tag as it’s a native feature of npm.

4

+1, thanks!

A couple of remarks:

  • Re-publishing after a partial failure: since the dist-tag is computed from the first package found on the registry, a re-run of a release that failed midway could find the version being published already there. The “higher than every final release already on npm” check should exclude the version being published (or use ≥), otherwise e.g. 18.10.0 would end up tagged stable-18.10.x instead of latest. Worth a test.
  • The change needs to be on every maintained branch that publishes packages (i.e. >= 18.0) before their next release, not only 18.4.x, otherwise any of them will keep overwriting latest.
  • To answer @surli’s question: IIUC stable-X.Y.x is only there because npm requires a dist-tag on every publish, and users are expected to use semver ranges (~18.4.0). Might be worth stating it explicitly in the proposal.

Thanks
PS: This post was co-written with Claude Code.

5

+1

Thanks,
Marius

6

+1

7

Thanks for your votes, I’ve adapted XWIKI-24828: npm packages are published with the latest dist-tag even when released from a maintenance branch by manuelleduc · Pull Request #6337 · xwiki/xwiki-platform · GitHub to your answers, and it is now ready for review.