How does versioning work for these packages?

[sdnts]

Hey all, I've upgraded to the new @phosphor-icons/react package, but I noticed that there are latest & next tags on NPM.
I'm assuming the next tag points to a "canary" of sorts, but it uses the same 2.x version range. This confuses my package manager (yarn 3 at the moment) because specifying version 2.0.13 makes it think a newer version is available (2.1.3) because of the higher minor version, but actually upgrading to 2.1.3 makes it think 2.0.13 is the latest because of the latest NPM tag.

While this may be a bug with yarn 3, I was still curious about which version I should be using. In my experience, next versions generally use a different version range to prevent this kind of problem. (like 3.0.1-alpha.1 / 3.0.1-rc.1 or something)

[rektdeckard]

Hi @sdnts, we do indeed use the next tag as a canary release version, and obviously latest as the stable version. We follow semantic versioning, so I find it odd practice to use a separate major version number to house canary releases -- what do you do when you exhaust all the major versions between stable and canary?

Typically we will "promote" a next-tagged version to latest when we feel it is ready to go mainstream, but if it helps to not confuse package managers, we can append some string garbage to then end of patch versions of canary releases in the future. For now, 2.0.13 (latest) is the package you should be using in prod. You can generally read our versioning as follows:

• latest tag is always what you should use in production
• major version indicates a breaking API change, breaking naming change, or other notable difference (when we migrated to our @phosphor-icons NPM namespace we began at 2.0.0 to indicate continuity with the previous version history ending at 1.4.x)
• minor version indicates icons have been added or modified, feature added, or substantive bug fixed
• patch version indicates minor bug fixes, bookkeeping

Additionally, we may increment versions to maintain consistency with our other libraries.

[sdnts]

Thanks for confirming @rektdeckard! I suppose this is a bug(?) or at least some sort of incompatibility in yarn 3. It's a tiny annoyance at best, really.

To answer your question: what I've generally seen/done is that the latest tag always points to the latest version like you do (so like v2.1.3), but the way people handle "canaries" is the next planned version number, appended with some kind of linearly increasing version (so like v2.2.0-alpha.1, v2.2.0-alpha.2, v2.2.0-alpha.342). Then you can promote this version when you feel like it (to v2.2.0). The next tag points to the latest of these "alpha" versions.

Some examples:
https://www.npmjs.com/package/prisma?activeTab=versions (they use <next-version>-dev.<increasing-number>)
https://www.npmjs.com/package/react?activeTab=versions (they use <next-version>-rc.<increasing-number>)
https://www.npmjs.com/package/remix?activeTab=versions (they use <next-version>-pre.<increasing-number>)

I hope I'm being clear!

[rektdeckard]

Adopting this from now on.