Versioning plan for F# in VS 15.6 and moving forward

[cartermp]

See https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1004-versioning-plan.md

---

This is a more detailed breakdown and tracking issue for #4112.

We have strong motivation to decouple versioning of the F# compiler and tools from the F# language and core library. We also wish to keep the F# language and F# Core library coupled in version numbers. The reasoning is as follows:

• The F# major language version number will change more and more slowly over time. Proposed and approved new features still fit snugly in the minor version number.
• The F# minor language version is expected to change, but not as often as tooling and SDK versions.
• Decoupling the FSharp.Compiler.Service version from the language version has proven to be a good thing, as it has allowed the adoption of SemVer and rapid iteration. A similar model can be applied for the F# compiler and tooling.
• Coupling the compiler version with the language version is not always done in other languages (e.g., C#), and such decoupling hasn't been a problem.

Here's what it should look like:

Visual Studio version	15.5 (current)	15.6	15.7	vNext
F# language version	4.1	4.1	4.4	4.x
FSharp.Core version	4.4.1.0	4.4.3.x	4.4.4.x	4.4.x.y
FSharp.Core NuGet package version	4.2.x	4.3.x	4.4.x	4.x.y
F# compiler banner	F# Compiler 4.1	F# Compiler 10.x.y for F# 4.1	F# Compiler 11.x.y for F# 4.4	F# Compiler XX.y.z for F# 4.x
VS product Name	Visual F# 4.1	Visual F# 10.x.y for F# 4.1	Visual F# 11.x.y for F# 4.4	Visual F# XX.y.z for F# 4.x
VS product details	Microsoft Visual F# 4.1	Microsoft Visual F# 10.x.y for F# 4.1	Microsoft Visual F# 11.x.y for F# 4.4	Microsoft Visual F# XX.y.z for F# 4.x
F# SDK version	4.1	10.x	11.x	ZZ.x
F# Compiler .dll version	4.4.1.0	10.x.y.z	11.x.y.z	WW.x.y.z
FSharp.Compiler.Tools version	4.1.x	10.x.y for F# 4.1	11.x.y for F# 4.4	XX.y.z for F# 4.x
VS Assembly versions	15.4.x.y	15.6.x.y	15.7.x.y	vNext.x.y

You'll note a few things:

• There will be no F# 4.2 or F# 4.3 language version - it will skip to F# 4.4. This is because it will bring the F# language, FSharp.Core, and FSharp.Core NuGet package back into sync.
• The Compiler and SDK version will start at 10.x.y, and so on. This is to ensure that the F# language version will never catch up, and lets us start on the path of SemVer.
• Visual Studio assembly versions will match the VS release. It should be plainly obvious if an assembly is a part of Visual Studio this way.
• FSharp.Compiler.Service is not a part of this plan. Given that it has already been on this separate versioning path, and may need to version independently of the assets Microsoft produces for a number of reasons, we intend on keeping it as-is.

We believe that this will make versioning a bit more sane moving forward, as it gives us the ability to rev tooling at a faster pace than the language, while also laying out a plan to align F# language versions, FSharp.Core versions, and FSharp.Core NuGet package versions.

[isaacabraham]

What if there's features in the Core library that could be released out of band from language changes?

[forki]

I wish we could find a way to sync the nuget version with the dll version

[chillitom]

Agree with @forki, the package version and the DLL versions not matching has caused issues for teams on many occasions.

Related: #3204

[cartermp]

@isaacabraham In general, I don't think we plan on releasing FSharp.Core functionality out of band from language choices, but the current versioning scheme of the binary and package do open up that possibility. It's up for discussion if that final version will be interpreted as a SemVer-style patch version or "new small features" version. I'd rather keep that version number for bug fixes.

@forki / @chillitom I'm not opposed to making the package version the same as the .dll version. @dsyme / @KevinRansom?

[forki]

I mean nobody cares about the concrete version number of anything. (outside of Redmond that is. Redmond has special rules). Just make it predictable and consistent. Like go over to 4.5 for everything. People will appreciate that.

[cartermp]

@forki do you have feedback on the above plan with respect to predictability? From our vantage point, this buys us that, largely because the compiler and tooling is free to follow SemVer and rev as-needed rather than attempt to align with a language version somehow.

[dsyme]

@forki's suggest to skip to F# 4.5 at next language update (and thus sync the assembly version and nuget package first two digits) looks quite reasonable. There is also a long industry tradition of skipping to .5 on version updates (for no particularly good reason!)

Visual Studio version	15.5 (current)	15.6	15.7	vNext
F# language version	4.1	4.1	4.5	4.x
FSharp.Core version	4.4.1.0	4.4.3.0	4.5.0.0	4.x.0.0
FSharp.Core NuGet package version	4.2.x	4.3.x	4.5.x	4.x.0
F# compiler banner	F# Compiler 4.1	F# Compiler 10.x.y for F# 4.1	F# Compiler 11.x.y for F# 4.5	F# Compiler XX.y.z for F# 4.x
VS product Name	Visual F# 4.1	Visual F# 10.x.y for F# 4.1	Visual F# 11.x.y for F# 4.5	Visual F# XX.y.z for F# 4.x
VS product details	Microsoft Visual F# 4.1	Microsoft Visual F# 10.x.y for F# 4.1	Microsoft Visual F# 11.x.y for F# 4.5	Microsoft Visual F# XX.y.z for F# 4.x
F# SDK version	4.1	10.x	11.x	ZZ.x
F# SDK Compiler .dll versions	4.4.1.0	10.x.y.z	11.x.y.z	WW.x.y.z
FSharp.Compiler.Tools version	4.1.x	10.x.y for F# 4.1	11.x.y for F# 4.5	XX.y.z for F# 4.x
VS Assembly versions	15.4.x.y	15.6.x.y	15.7.x.y	vNext.x.y

There's a question whether the nuget package version should be 4.5.x or 4.5.0.x (the nuget package may need incremental updates where we don't bump the assembly version of the assembly inside it). Very few nuget packages use 4 digits however and @KevinRansom was dubious about whether all tooling would work if we did

[cartermp]

Any technical concerns with other tools? I like the idea overall.

[cartermp]

I spoke with @KevinRansom today, and we don't currently see a technical issue with aligning the FSharp.Core binary and FSharp.Core package to 4.5.0.0 and 4.5.0, respectively, in a 15.7 timeframe. Let's assume that this is the plan.

There is, however, the question that @isaacabraham raised, and @KevinRansom and I spoke about it a bit. Imagine the following situation:

• F# language version revs once over a year
• FSharp.Core version could version twice over a year
• F# compiler version will version at least twice over a year

In the current proposal, FSharp.Core is held off from versioning due to the F# language version not being ready. @dsyme, what would be your reasoning for keeping FSharp.Core and F# language versions in lockstep?

[cartermp]

I've created an RFC here: fsharp/fslang-design#249

It's probably best to discuss there

[dsyme]

In the current proposal, FSharp.Core is held off from versioning due to the F# language version not being ready. @dsyme, what would be your reasoning for keeping FSharp.Core and F# language versions in lockstep?

There's a lot of simplicity value to keeping the versions aligned. So I think we should probably make it that from 4.5 onwards F# minor language revisions can just be "small" or even empty (i.e. F# 4.8 might be the same language as F# 4.7 with some improvements/adjustments to FSharp.Core).

[ctaggart]

Traceability is also important. It would be great if there was a way to to get the git commit used for each version produced. Ideally, this information would be available multiple ways:

• git tags for versions
• the sha in an assembly attribute
• some versions document or wiki page

Today, I'm trying to hunt down a sprintf problem causing Unity to blow up and it is really difficult to trace. The F# Compiler version shipping with Mono is not kept in sync with the one from dotnet sdk or Visual Studio. It would be great if there was a way to keep them in sync. Long term, I'm hoping we can just use dotnet from Unity and not have to deal with these Mono differences, but not sure how far out that is.

[cartermp]

@ctaggart In terms of process, tags are the easiest option. We'll have to be disciplined about tagging each release.

[charlesroddie]

Regardless of the decision here, ordinary users will need this information in accessible form. In order to decide which Nuget package to use and what combination of numbers should be in project files.

That information could be the first three rows of the table above and I would suggest putting it in or linking to it from the FSharp.Core nuget description.

The most current document that I can find is https://fsharp.github.io/2015/04/18/fsharp-core-notes.html#fsharpcore-version-numbers , but it is out of date and I think lists the wrong FSharp.Core versions for PCL projects with F#4.1.

[cartermp]

Closing this, as we have implemented the RFC. Further discussions around FSharp.Core are here: fsharp/fslang-design#250

As for where version numbers are presented online, this is a matter of the owners of those various web properties updating version numbers accordingly. Release notes for what we control will be updated with links to the RFC.