[FEATURE] method .inc - option to set prerelease identifier numbering to be zero-based or one-based

[bryanfarrell]

Hello,

As stated in the documentation:

The method .inc takes an additional identifier string argument that will append the value of the string as a prerelease identifier: semver.inc('1.2.3', 'prerelease', 'beta') // '1.2.4-beta.0'

This functionality is great the issue I have however is that it does not follow the Semantic Versioning 2.0.0 pattern. For example, semver.org itself had two release candidates for version 2.0.0, 2.0.0-rc.1 and 2.0.0-rc.2.

Based on semver.org's very own use case as an example, It would seem to me that the quoted example above should return 1.2.4.beta.1.

Here is an example of how I would typically increment my version numbers over time:

const semver = require('semver');
var ver = '0.1.0'; console.log(ver); // 0.1.0 initial version
ver = semver.inc(ver, 'minor'); console.log(ver); // 0.2.0
ver = semver.inc(ver, 'minor'); console.log(ver); // 0.3.0
ver = semver.inc(ver, 'patch'); console.log(ver); // 0.3.1
ver = semver.inc(ver, 'patch'); console.log(ver); // 0.3.2
ver = semver.inc(ver, 'premajor', 'rc'); console.log(ver); // 1.0.0-rc.0 expecting 1.0.0-rc.1
ver = semver.inc(ver, 'prerelease', 'rc'); console.log(ver); // 1.0.0-rc.1 expecting 1.0.0-rc.2
ver = semver.inc(ver, 'major'); console.log(ver); // 1.0.0
ver = semver.inc(ver, 'minor'); console.log(ver); // 1.1.0
ver = semver.inc(ver, 'minor'); console.log(ver); // 1.2.0
ver = semver.inc(ver, 'patch'); console.log(ver); // 1.2.1
ver = semver.inc(ver, 'patch'); console.log(ver); // 1.2.2
ver = semver.inc(ver, 'premajor', 'rc'); console.log(ver); // 2.0.0-rc.0 expecting 2.0.0-rc.1
ver = semver.inc(ver, 'major'); console.log(ver); // 2.0.0

As you can see when I increment to a premajor release candidate I am expecting it to start as rc.1 and not rc.0 like it does now. In my opinion having it start at zero does not make any sense as that would be like starting with an initial version of '0.0.0' instead of '0.1.0' as recommended by semver.org.

Now I understand that many people may prefer that all prerelease tags start with zero which is why I am suggesting an additional option to the method .inc as apposed to changing the current functionality.

I have a suggestion as to how to add the functionality I am looking for without removing the existing functionality. This would be to add an optional parameter that indicates if a prerelease identifier is zero-based or one-based, with the default being zero-based to keep current functionality.

I looked at the code in SemVer.prototype.inc = function(release, identifier) {, specifically case 'pre':, at the if (identifier) { block, and I was able to get my expected behavior to work by changing [identifier, 0] to [identifier, 1] and also this.prerelease.push(0); to this.prerelease.push(1);.

I am hoping you can look into adding this as an option to the method so that everyone can choose between zero-based or one-based prerelease identifier numbering based on what they feel is their own best use case.

Thank you,

Bryan

[lukekarrys]

The @npm/cli-team would also be interested in this. I wrote something similar for how we version the CLI itself here: https://github.com/npm/template-oss/blob/main/lib/release-please/version.js

It would be great to get feedback on how others would expect this to work. The code I linked to above is only being used by the CLI and its dependencies at the moment, but it would be great to get that behavior directly from semver.