Confusing deprecation of Version.setPreReleaseVersion()

[rubenyo-group9]

Hello,

While updating our company’s Gradle scripting with jsemver (via the axion-release-plugin), I ran into a confusing deprecation.

Code example

In this example, we try to set a prerelease version if none exists yet.

if (context.currentVersion.preReleaseVersion().isEmpty()) {
    return context.currentVersion.incrementMinorVersion()
        .setPreReleaseVersion("rc.1");
}

Problem

• Version.setPreReleaseVersion(String) is deprecated (link), with a Javadoc note suggesting nextPreReleaseVersion(String...) instead.
• However, nextPreReleaseVersion fails when no pre-release version exists because of the isPreRelease() check.
• This makes it impossible to replace the deprecated call in the example above.

Expected behavior

Either:

1. The deprecation message should be updated to reflect the correct replacement (or lack thereof) when no pre-release exists.
2. Or, a non-deprecated API should exist for the above code fragment (setting the first pre-release version).

[zafarkhaja]

Hi,

Indeed the Javadoc comment is wrong and misleading because setPreReleaseVersion() wasn't supposed to be replaced at all. Hence, the call is not delegated to a replacement method, as in the case of incrementPreReleaseVersion() which is actually the one replaced by nextPreReleaseVersion(). Obviously it's a Javadoc "bug", which I'll need to fix. So, thank you for taking the time to report it.

The reason behind dropping setPreReleaseVersion(), which allows decrementing of versions (1.0.0 -> 1.0.0-beta), was to align the Version's API with SemVer which is rather concerned with incrementing of versions. If needed, Version.Builder can be used to arbitrarily change any number or suffix of a version bypassing SemVer's precedence rules.

In your case a likely code update would be as follows

if (context.currentVersion.isStable()) {
    return context.currentVersion.nextMinorVersion("rc.1");
}