New versioning strategy

[n3dst4]

Summary of issue

FVTT's version handling for packages is fucky because it doesn't recognise prerelease signifiers.

I have been using prerelease signifiers since day dot. It turnms out that anyone who used a prerelease of INVESTIGATOR won't automatically get upgraded to the corresponding full release because FVTT's dumb isNewerVersion thinks that 1.2.3-alpha.1 is newer than 1.2.3 (they would get upgraded when 1.2.4 or 1.3.0 comes out.)

We need to consider two aspects here:

• Do we want a different version structure?
• How to replace prerelease signifiers

Version structure

FVTT does not have strong opinions about versioning. They recommend semver (without extra signifiers) for system packages, although it's not very clear why. They recommend [generation].[build] or calendar versioning for "user-facing packages, such as content and modules."

See Introduction to Development (scroll down.)

The benefits of semver don't really obtain for a FVTT package. There is no public API (well... there is, in the case of INVESTIGATOR, but that's not the purpose of it) and generally consumers will always wajnt to upgrade to the latest version. Information about FVTT version requirements or other package requirements is held in the package manifest, not communicated through the version number.

The fine distinction between 8.2.0 (new feature!) and 8.2.1 (oopsy!) is lost on most consumers.

The major version for INVESTIGATOR has been incremented for two reasons in the past:

First, dropping support for an older FVTT version. This kinda feels like a semver "breaking change"... but in fact the useful info is incidental. We could drop support for an FVTT version without bumping trhe major version and zero people would care.

Secondly, when we've had branding changes. These feel like "generational" or "marketing" numbers. Not to say that they're not important, but they're for human consumption, not technical consumption.

I think I'm coming round to generation/incrementing versioning.

How do we replace prerelease signifiers?

If we have a simple incrementing number, we just need a way to tag a release as either prerelease, or full release.

What happens currently?

Currently we do a release by manually setting the version in package.json and system.json, then running a script. The manual version setting sounds awkward but is actually good - it's like a double check of "did you really mean to do this release?" The script:

1. makes sure we're on main
2. commits the changes
3. creates a tag of the version with v prefix, i.e. v1.2.3
4. pushes the tag

The shared CI/CD workflow looks for tag pushes where the tag matches vN.N.N or vN.N.N-xxxxx (any other tag is ignored and the build just does the usual checks.)

It it finds such a tag, it will perform some sort of release. If there is a prerelease signifier (-xxxxx above) it will do prerelease. This means the package is pushed to GitHub releases as prerelease, and the automated FVTT publish does NOT happen.

If there is no prerelease signifier, it does a full release to GitHub releases, and then goes ahead with the FVTT publish.

Proposal

Get rid of the current do-release script and replace it with do-prerelease and do-full-release

Both scripts check:

1. the version number in package.json and system.json is the same
2. there’s just major.minor, no pre-release signifier and no patch number

Both scripts do roughly the same thing. The big difference is that do-prerelease, instead of pushing a tag of the form vX.Y, pushes a tag of the form prerelease-vX.Y.

CI workflow:

Currently we look for X.Y.Z-prereleasesignifier.

Most of the workflow is the same in either event, but if prereleasesignifier is present, we 1. Do a prerelease to GitHub not a full release and 2. Do NOT publish to Foundry.

As far as I recall (CHECK THIS) we never actually use the string content of the prerelease signifier - we just care whether it was present or not.

I propose that we extend the regex or write an extra step to detect the new tag formats. And set prerelease id the tag start prerelease-.