Version scheme to use in Paket

[mexx]

While working on a fix for #263 I've looked inside the SemVer spec, NuGet docs and code.

The current NuGet version supports SemVer 1.0.0 spec.
Additionally it allows the legacy versions with 4 numeric parts.
The current developed NuGet version (3.x) will support the SemVer v2.0.0 spec. Blog post

Paket currently goes for support of SemVer v1 with the extension for a build part, like NuGet >= v1.6.

If I got it correctly, we don't want to simply copy NuGet's behavior.
With it I mean we have to decide which version scheme we want to follow and fully support.
I want to underline that correctly supporting SemVer 1.0.0 and 2.0.0 side-by-side will be very difficult, as the specs defines different strategies for handling i.e. sorting of pre-release versions.

I understand the wish to make the transition to Paket as simple as possible, but I would suggest to be very strict at the point of versioning.
We could provide a possibility for the user to define the version scheme to use or simply go for SemVer v2?

Note
When NuGet v3 gets released we would need to support SemVer v2 anyway and handle different NuGet versions in convert-from-nuget process correctly.

[forki]

I vote for semver 2 + "accepting nuget versions" even if we order
differently.
On Oct 23, 2014 12:03 AM, "Max Malook" notifications@github.com wrote:

While working on a fix for #263
#263 I've looked inside the
SemVer spec, NuGet docs and code.

The current NuGet version supports SemVer 1.0.0 spec.
Additionally it allows the legacy versions with 4 numeric parts.
The current developed NuGet version (3.x) will support the SemVer v2.0.0
spec. Blog post
http://blog.nuget.org/20140924/supporting-semver-2.0.0.html

Paket currently goes for support of SemVer v1 with the extension for a
build part, like NuGet >= v1.6.

If I got it correctly, we don't want to simply copy NuGet's behavior.
With it I mean we have to decide which version scheme we want to follow
and fully support.
I want to underline that correctly supporting SemVer 1.0.0 and 2.0.0
side-by-side will be very difficult, as the specs defines different
strategies for handling i.e. sorting of pre-release versions.

I understand the wish to make the transition to Paket as simple as
possible, but I would suggest to be very strict at the point of versioning.
We could provide a possibility for the user to define the version scheme
to use or simply go for SemVer v2?

Note
When NuGet v3 gets released we would need to support SemVer v2 anyway and
handle different NuGet versions in convert-from-nuget process correctly.

—
Reply to this email directly or view it on GitHub
#289.

[dnauck]

+1 for @forki 's suggestion

[agross]

Sounds good!

Alex

Alexander Groß
Tiny phone, tiny mail

On Thu, Oct 23, 2014 at 10:54 AM, Daniel Nauck notifications@github.com
wrote:

+1 for @forki 's suggestion

Reply to this email directly or view it on GitHub:
#289 (comment)

[mexx]

@forki What do you mean by "accepting nuget versions", can you elaborate more on it?

[forki]

It's more a hint to the future. I think we should understand nuget
versions, but we should never ever generate new version nos. which are not
semver compliant.
On Oct 23, 2014 10:09 PM, "Max Malook" notifications@github.com wrote:

@forki https://github.com/forki What do you mean by "accepting nuget
versions", can you elaborate more on it?

—
Reply to this email directly or view it on GitHub
#289 (comment).

[agross]

I wonder what NuGet will do w.r.t. backward compatibility. Not all packages will immediately update their versions, some. nuget v3-powered projects will still have to rely on semver v1 packages.

So, I feel we should support both.

Can we detect whether the prerelease version is SemVer v1 or v2? I think we can assume that all preleases for a version use a single format.

But perhaps I got something wrong. In this case, please enlighten me :-)

[khellang]

The difference between the two is mostly in pre-release identifiers:

An identifier can only consist of ASCII numerics plus dash [0-9A-Za-z-].

• v1 can only contain one identifier, e.g. 1.0.0-beta2-234.
• v2 can contain multiple .-separated identifiers, e.g. 1.0.0-beta2.234.

If all major, minor and patch versions are the same, the pre-release version is used to determine precedence:

Identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order.
Numeric identifiers always have lower precedence than non-numeric identifiers.
A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.

v2 also has a notion of build metadata, denoted by a + followed by one or more .-separated identifiers, e.g. 1.0.0-beta+1234.

Based on this, if the version contains a . or a + (though build metadata doesn't affect precedence and should be stripped), I think we can safely assume it's v2, otherwise it's v1.

For reference, see the BNF grammar.

[mexx]

The difference is in the pre-release identifiers and notion of build metadata, as @khellang already mentioned.

According to v2 spec

Numeric identifiers MUST NOT include leading zeroes

Further according to provided BNF grammar identifiers like 001, i.e. consisting only from digits and having leading zeros, are not valid pre-release identifiers. I don't know how often do they exist in the wild.

Basically v1 pre-release identifiers would be parsed as one part v2 identifiers. Except the cases where the identifier would be invalid in v2, like mentioned earlier 001.

@agross As NuGet only sorts in lexographic ASCII order the only difference in sorting would result when v2 would detect numeric identifiers, as they have lower precedence that alphanumeric ones and would be sorted numerically in their category. This newly detected numeric identifiers would break the order produced by previous NuGet versions.
For NuGet it's not that problem, as the user have to decide to use the new version explicitly and have to deal with this breaking change in the sorting behavior.

I don't know how strict we want to follow SemVer spec. I understand that with strict implementation we could have problems with some package versions, but for now I would go for this conflict. Maybe it's not that often in the wild.

Regarding legacy build number part of NuGet packages, we could interpret them as first pre-release identifier as they take precedence in NuGet's version sorting over SemVer pre-release identifiers and are sorted numerically.

Further Paket should fail if it can't recognize the version string completely, it would prevent bugs like #263.