More flexible version numbers (still valid semver)

[klonos]

Using tiny int for the values of version_major/version_minor/version_patch seems to be limiting...

I initially tried creating a release for a new project, and decided to go with 1.x-1.20230726.001. The project node was created on borg, however no release node. When I tried adding a release manually (via node/add/project-release/[PROJECT_ID]), I got the following error:

SQLSTATE[22003]: Numeric value out of range: 1264 Out of range value for column 'version_minor' at row 1

I then decided to change the version to 1.x-2023.07.26+001 (the +xxx suffix is still valid semver - it's called a "build number" or "build metadata"), but got the following error from the packager (in a PACKAGING_ERROR_LOG.txt file attached to the GitHub release assets this time):

The version string "1.x-2023.07.26+001" does not match the required format of the "project_release" node type.

Next, I tried 1.x-2023.07.26-build001, but again no release on the borg side. Manually trying to create the release threw this error:

SQLSTATE[22003]: Numeric value out of range: 1264 Out of range value for column 'version_major' at row 1

So I finally settled for 1.x-23.07.26-build001 as the release number, which worked, however I would like us to allow more flexibility:

• update the db schema, to increase the max for version_major/version_minor/version_patch from tinyint to at least smallint (ideally proper integer though).
• allow for +xyz (plus) suffixes besides the -xyz ones already allowed (dash)

[klonos]

Putting a copy of https://regexr.com/39s32 here for posterity:

Simplest valid/invalid cases of semver:

invalid, not minimal MAJOR.MINOR.PATCH format
1
1.1

valid, meets minimal MAJOR.MINOIR.PATCH
1.1.1

More complex but still valid semver:

pre-release form (paragraph 9 of specs)
1.0.0-alpha
1.0.0-alpha.1
1.0.0-0.3.7
1.0.0-x.7.z.92

build metadata immediately following the pre-release (paragraph 10 of specs) 
1.0.0-alpha+001

build metadata immediately following the patch (paragraph 10 of specs)
1.0.0+20130313144700

build metadata immediately following the pre-release (paragraph 10 of specs)
1.0.0-beta+exp.sha.5114f85

Invalid

invalid pre-release metadata (empty identifier[s], paragraph 9 of specs)
1.0.0-.123
1.0.0-...
1.0.0-123.
1.0.0-+

[klonos]

Note to self (re schema updates): https://api.drupal.org/api/drupal/modules%21system%21system.api.php/function/hook_schema_alter/7.x#comment-62950

[jenlampton]

I'm not sure this is a good idea (so I don't think we should support it). Having really whacky release numbers (in comparison to all other Backdrop releases) is likely to only confuse people.

Just because something is still valid semantic versioning, doesn't mean we should bend over backwards to support it. There's plenty of flexibility within our current system.

I then decided to change the version to 1.x-2023.07.26+001 (the +xxx suffix is still valid semver - it's called a "build number" or "build metadata"), but got the following error from the packager (in a PACKAGING_ERROR_LOG.txt file attached to the GitHub release assets this time):

You are welcome to use the -alpha or -dev` style additions extensions with a hyphen, but don't use the plus.

I think it would be better to update the documentation telling people not to do this :)

[jenlampton]

Here is the release number documentation we are currently using: https://docs.backdropcms.org/documentation/maintaining-a-contributed-project

I've added a new section that advises against unreasonable numbering:

For your sanity, and the sanity of people using the project, use small sequential numbers for each release. Something like 1.x-1.20230726.001 wouldn't be sensible, since there are not 20230726 feature releases for your project.

We could also add a section telling people not to use the plus for a build number, but if you are the only one who's ever run into this, and only while experimenting, it's probably not necessary. Build numbers are usually for something that's built, and since PHP does not usually need to be complied or assembled, it doesn't really make sense here.