Add plan for .NET Core SDK version numbers

[KathleenDollard]

Builds of the .NET Core SDK will soon reflect this scheme described in this document.

[bgever]

I like this proposal, much clearer and I like the ability to instantly spot the difference between SDK and Runtime. That was confusing for global.json, especially related to applying security patches of the Runtime while using an older SDK.

[akoeplinger]

should probably be .NET Core [short SDK version] SDK (v [full SDK version]) to match with the example below.

[KathleenDollard]

Thank you for the catch!!!

(while they are the same, technically that first occurrence is the short runtime)

[SteveDesmond-ca]

2 questions:

1. Was it considered / would it make sense to / what were the reasonings against going to a 4-point version for the SDK, where the first 3 are the full runtime semver, so that it's easy to see what the whole runtime version is without a lookup table?

2. Since semver is going away, is it still safe to assume that new features will only be added to the newest runtime version? Or will there need to be a feature matrix of "feature x is in 2.1.200+ and 2.2.100+, feature y is in 2.1.300+ and 2.2.200+" etc.?

[KathleenDollard]

@SteveDesmond-ca

1. We did consider a 4 point version number. It would be a breaking change because people may have taken a dependency on the third position indicating patch, and would thus fail to realize a patch was released.

The variation of the 4 point version number would also mean that if you do not transition to the 4 point system in your automated tools, you can't tell the difference between SDKs at all.

2. Yes. We anticipate adding features in the tip of the SDK: the newest runtime. The SDK will be backward compatible so you can work with any previous version of the Runtime. So, if we introduce something in 2.2.200+ that you want to use with an app targeting 2.1.x Runtime, you would download the Runtime separately. We hope people will work with the latest version of the SDK with whatever (lower) version of the Runtime is desired.

Does that clarify/answer your question?

[tmds]

The released SDK for 2.0 runtime has number 2.1.4. If this scheme were already in place, it would have been versioned 2.0.104. Will the next patch on this SDK be 2.0.105?

[KathleenDollard]

@tmds We will not version downward for non-preview builds. To support this, patches will stay in the 2.1.n series until we go to the next feature release at 2.1.100. We will not align with the runtime until .NET Core 2.1 SDK (v 2.1.300) which will contain and align with .NET Core Runtime 2.1.0.

The transition is a bit sloppy because we were already in the 2.1 series for the SDK. Does this make sense?

@livarcocc Please proof this message, to ensure it is correct.

[bording]

@KathleenDollard As weird as it might be, it seems like it might be better to skip the 2.1 runtime release and jump to 2.2 as the version. That way you could align the runtime and SDK as .NET Core 2.2 SDK (v 2.2.100) and not have this weird state where some 2.1 SDKs have a 2.0 runtime and some have 2.1.

[KathleenDollard]

We walked down that road, and felt it was too much risk around the runtime.

[tmds]

We will not version downward for non-preview builds.

I think it would be good to put the 2.0 runtime sdk on this scheme as soon as possible. That is:
Next patch of 2.0.3 sdk is 2.0.104
Next patch of 2.1.4 sdk is 2.0.205
I don't see a reason why you'd want to keep this at 2.1.x? I think it just makes things more confusing (for humans and tools).

[dasMulli]

I don't recommend putting newer things into distributions with lower version numbers. Keeping the status quo until .NET Core 2.1 is released (a few months?) will probably not hurt much.

Unless.. what's the plan for additional 2.0.* runtime servicing releases after 2.1 has shipped?

Will there be additional 2.1.1xx/2.1.2xx releases of the SDK carrying newer runtimes or will the recommended approach be "use the newest SDK and install the newest 2.0.* runtime if you need it" (could be a 2.1.3xx SDK)?

I'd favour the latter one. In my opinion, the SDK shouldn't be viewed as the main distribution vehicle for runtimes (although it probably technically is; but you shouldn't need to keep updating an older version of the SDK that you aren't going to use anyway)

[tmds]

I don't recommend putting newer things into distributions with lower version numbers.

I agree in general. The main reason is the package manager would have a hard time figuring out what is the newer version.
I think it is safe to do it here:

• Microsoft packages (so far) require explicit specification of the patch version on installation. So these packages are not patching themselves. They install side-by-side.
• The 2.1.x SDK isn't buildable by non-Microsoft parties (not supported yet in source-build). So, non-Microsoft packages (e.g. RHEL, Fedora) are still at 2.0.3. So here we rely on the package manager, but the version will go up when we apply the scheme.

@dasMulli wdyt?

Unless.. what's the plan for additional 2.0.* runtime servicing releases after 2.1 has shipped?
Will there be additional 2.1.1xx/2.1.2xx releases of the SDK carrying newer runtimes

Good questions. My understanding (which may be wrong):

• to target runtime 2.x, you need sdk 2.y (y >= x).
• when there is a patch to runtime 2.x, there will be an associated sdk 2.x release.

[poke]

@dasMulli

or will the recommended approach be "use the newest SDK and install the newest 2.0.* runtime if you need it"

I think that’s how it should be done, if I read the message above by @KathleenDollard correctly:

We hope people will work with the latest version of the SDK with whatever (lower) version of the Runtime is desired.

[KathleenDollard]

@tmds

I think it would be good to put the 2.0 runtime sdk on this scheme as soon as possible. That is:
Next patch of 2.0.3 sdk is 2.0.104
Next patch of 2.1.4 sdk is 2.0.205
I don't see a reason why you'd want to keep this at 2.1.x? I think it just makes things more confusing (for humans and tools).

For the 2.1 SDK series: When we made this decision, we had not finalized that we would skip the "0 series" in future patches, and you've just convinced me skipping them was a good idea. Basically, the current patch series zero. 2.1.4 is effectively 2.1.004, except we don't left pad. Yes, that is confusing, and we will not do it going forward.

I'm surprised by the 2.0 series suggestion. I thought that folks would want that series to be very stable and predictable. Would you have a different thought on that if source builds were in the 2.1 series?

[KathleenDollard]

Will there be additional 2.1.1xx/2.1.2xx releases of the SDK carrying newer runtimes or will the recommended approach be "use the newest SDK and install the newest 2.0.* runtime if you need it" (could be a 2.1.3xx SDK)?

We do not plan to put the new runtime into old SDKs. In fact, old SDKs are capped and don't work with newer runtimes because it is an untested scenario.

You are correct: We encourage use of the newest SDK and the runtime that makes sense for your project. We like our new ones and think they are awesome! but we know folks have many demands on their project decisions.

(We continue to support global.json for locking down the SDK when needed)

[KathleenDollard]

Good questions. My understanding (which may be wrong):

• to target runtime 2.x, you need sdk 2.y (y >= x).
• when there is a patch to runtime 2.x, there will be an associated sdk 2.x release.

You are correct. We believe the SDK is the most natural delivery vehicle for the runtime for devs.

[tmds]

Basically, the current patch series zero. 2.1.4 is effectively 2.1.004

That is not correct. The 2.1.4 series does not support 2.1 runtime. In the scheme proposed here, It effectively is 2.0.204.

My suggestion is to align the existing SDKs for 2.0 runtime (https://github.com/dotnet/core/blob/master/release-notes/download-archive.md) with this versioning scheme on their next patch release.
To avoid people to think that 2.1.5 supports .NET runtime 2.1, we version it 2.0.205.

[dasMulli]

We believe the SDK is the most natural delivery vehicle for the runtime for devs.

@KathleenDollard It is. but I don't think it should be.. Servicing "old" SDKs with newer runtimes is okay-ish but contributes to the believe that one needs e.g. an 1.1.* SDK to build 1.1.* apps, because the SDK for that branch is listed next to the release.

Maybe a quick fix could be done here, e.g. naming the downloads / executables .NET Core 2.0.4 with SDK. That way the SDK itself is no longer the delivery vehicle but rather a runtime-related installer. AFAIK there is a repo-merge planned for dotnet/sdk and dotnet/cli with moving the installer builds out of that repo.. So the there wouldn't be a technical necessity to increase the SDK version for new runtime+SDK installers. - @livarcocc is that on the horizon?

A difficulty with this would be how to manage the "latest known patch release" for self-contained applications - the 1.0 and 1.1 branches had a known version baked into their build targets, for 2.0 this was removed (or rather, untouched in updates) due to technical issues.
Depending on how this is going to be addressed, this may affect versioning.

[dasMulli]

@KathleenDollard please also create an announcement issue to ask users to delete old 2.2.0 preview builds when a public 2.1.300 preview build is released or else they are left with potentially unreliable tooling (instance of this: https://github.com/dotnet/cli/issues/8531).

[mairaw]

Can we establish when this going forward starts?

[dasMulli]

Can this be merged now that the CLI has adapted to this scheme? (it's better to link to an md file (that's not in a fork) than a PR)

[jouniheikniemi]

Why is 2.1.203 picked? (given "use latest servicing version" verbiage above)

[jouniheikniemi]

Oh OK. After I read it for, like, the third time, I realize that this document becomes way more obvious when you realize that a feature release is of the format "x.y.z**". That idea is embedded in line 17, but I failed to understand its implications twice. Only goes to show how hard it is to break semver and get yourself understood.

[jouniheikniemi]

I guess this kind of servicing release refers to one of the type like line 30, where the runtime version is changed as well. Would it be a good idea to also add an example for a release like line 29 where the runtime isn't revved at all?

[Nirmal4G]

@dasMulli @KathleenDollard The following might be a good solution!

While it's good to have the Runtime and SDK packaged together as a single installer with a single version to get the best Out Of Box Experience, this was the same reason that MSBuild separated from .NETFramework and Bundled with VisualStudio. So, by that logic, instead of repeating history why can't we provide single installer for all versions .NET Core Runtime and SDK (even future versions).

You could effectively provide a single .NET Core SDK installer/version manger that will list all the (supported) versions and download the required SDK/Runtime versions combo provided by the user.

kind of like Visual Studio 2017 Setup and Android SDK manager

[benaadams]

Should this be merged? Spent a while trying to look for the version numbering scheme in the docs