Nuget Package Versioning scheme change

[amaitland]

CEF has changed it's versioning scheme dramatically. The full details are at https://bitbucket.org/chromiumembedded/cef/issues/2596/improve-cef-version-number-format

CEF version numbers

• Old version number format 3.3683.1920
• New version number format 73.1.12

As a result it doesn't really make sense to version the CefSharp packages as 73.0.0.

CefSharp version numbers

• Old version number 73.0.0
• New initial release version number 73.1.12.0
• New point release version number 73.1.12.1

The first part of the version will reflect the CEF version the packages are based on.

[amaitland]

The build scripts have been updated to support the new format in 1f39e42

master was upgraded to CEF 73.1.12+gee4b49f+chromium-73.0.3683.75 / Chromium 73.0.3683.75.

CI build https://ci.appveyor.com/project/cefsharp/cefsharp/builds/23387231

Looks like the Nuget package names still need an additional .0 added

[amaitland]

A specific version number is in the form Major.Minor.Patch[-Suffix], where the components have the following meanings:

Major: Breaking changes
Minor: New features, but backwards compatible
Patch: Backwards compatible bug fixes only
-Suffix (optional): a hyphen followed by a string denoting a pre-release version (following the Semantic Versioning or SemVer 1.0 convention).

https://docs.microsoft.com/en-us/nuget/reference/package-versioning

So looking closer at the Nuget spec and it appears to only support Major.Minor.Patch, so I'll have to rethink the approach, open to suggestions.

[amaitland]

The Nuget issue is #3050, apparently the current behaviour is a regression, that they don't seem particularly interesting in fixing.

Comments suggest that 73.1.12.0 and 73.1.12 are treated the same. It's only when the trailing digit is a 0 that it's stripped off.

I've found enough projects on Nuget.org that use a longer numbering scheme that I don't think we'll be pioneering new ground (https://www.nuget.org/packages/angularjs/ is one such project).

The two options are just start with 73.1.12 and 73.1.12.1 would be the next release, or do what angularjs does and start from ``73.1.12.1`.

I'm leaning towards starting at 73.1.12.1 at this stage, though open to suggestions.

[perlun]

@amaitland I'm not really involved in the project at the moment, so feel free to take my comments lightly. Having that said, I do think that the "NuGet format" is the way to go, and 73.1.12.1-style should be avoided. Semantic Versioning defines it this way. (I'm sure you're already aware of this, so bear with me for the repetition.)

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Some suggestions:

• You can use a -Suffix approach, as suggested above. However, this will be treated as a prerelease which is really not what we want, it gives the false impression for stable CefSharp versions.
• You can use the +foo approach, where the CEF version could be embedded in the foo part (which explicitly is provided for holding metadata about a package). We would still have to bump the major/minor/patch version when releasing a new CefSharp version though, since the "[b]uild metadata SHOULD be ignored when determining version precedence". Also, I'm not sure it would be supported by NuGet but it's worth looking into.
• You could use some clever scheme, like 73.1.120 (i.e. just adding a zero at the end; this will allow you to release up to 10 CefSharp versions for a particular CEF version which is typically enough)

Go with whatever you feel is appropriate, but my 0,02€ is that I think that (some form of) SemVer should be followed. I have seen in other programming languages where other formats have been adopted and I definitely think it's better to standardize on (something reasonably) SemVer whenever at all possible; all other schemes tend to make people confused.

[amaitland]

@perlun Comments are welcome, thanks 👍

• You can use a -Suffix approach, as suggested above. However, this will be treated as a prerelease which is really not what we want, it gives the false impression for stable CefSharp versions.

Don't really think this is an option.

• You can use the +foo approach, where the CEF version could be embedded in the foo part (which explicitly is provided for holding metadata about a package). We would still have to bump the major/minor/patch version when releasing a new CefSharp version though, since the "[b]uild metadata SHOULD be ignored when determining version precedence". Also, I'm not sure it would be supported by NuGet but it's worth looking into.

I had ruled this out as metadata would make the packages SemVer 2.0.0. You can only consume a SemVer 2.0.0 package with Nuget 4.3.0+ and Visual Studio 2017 version 15.3+. See references below.

• You could use some clever scheme, like 73.1.120 (i.e. just adding a zero at the end; this will allow you to release up to 10 CefSharp versions for a particular CEF version which is typically enough)

A clever idea, thanks for the suggestion 👍 Sounds workable, this could be a sensible way forward.

I have seen in other programming languages where other formats have been adopted and I definitely think it's better to standardize on (something reasonably) SemVer whenever at all possible; all other schemes tend to make people confused.

A four part version number is the .Net standard for assembly versioning. Most dlls on Windows confirm to a four part version number, at least that's my understanding. Microsoft themselves have a few packages with a four part version number, one example is https://www.nuget.org/packages/Microsoft.IdentityModel.Protocol.Extensions/ (There are plenty of other examples of projects using a similar scheme).

So whilst it's not technically SemVer, it should be valid from a Nuget point of view. So I do consider this a valid option.

References

NuGet currently supports SemVer 1.0.0 with additional support for four part version numbers to work with System.Version

https://github.com/NuGet/Home/wiki/SemVer-2.0.0-support

With NuGet 4.3.0+ and Visual Studio 2017 version 15.3+, NuGet supports Semantic Versioning 2.0.0.
Certain semantics of SemVer v2.0.0 are not supported in older clients. NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true:

The pre-release label is dot-separated, for example, 1.0.0-alpha.1
The version has build-metadata, for example, 1.0.0+githash

https://docs.microsoft.com/en-us/nuget/reference/package-versioning

Example of package using SemVer 2.0.0 is https://www.nuget.org/packages/NuGet.Frameworks/5.0.0-rtm.5856 If you open it in the browser it has a clear warning. It also has -rtm which I think is just confusing as it claims to be a prerelease.

[amaitland]

I'll go with the approach suggested by @perlun and see how it goes, we can always make changes for the next major release.

The initial version will be 73.1.120, the -pre release will be 73.1.120-pre01.

[amaitland]

New versioning scheme is in effect. 73.1.120-pre01 should appear on Nuget.org shortly.