.NET Core 2+ Naming and Versioning

The .NET Core product includes a set of components and files that customers are asked to understand: installer packages, NuGet packages and multiple .NET Core distributions. Some of the components version together and others don't, which causes confusion. The 2.0 release will have a coherent versioning and naming strategy for all .NET Core components and distributions, which includes web pages, installers (and associated UI) and NuGet packages.

A major version boundary is the right time to make this level of change. In fact, this change is the major reason to jump to .NET Core version to "2.0".

First Principles

1. Version all .NET Core distributions as 2.0.0 for the first release and then move forward together.
2. File and package names represent the component or collection and its version. Version divergence will be reconciled at minor and major version boundaries.
3. Installers that chain multiple components should clearly communicate the high order versions somewhere in the UI.

.NET Core 2.x file name and versioning

.NET Core 2.x will use the following format for file distributions:

[product]-[component]-[major].[minor].[patch]-[previewN]-[optional build #]-[rid].[file ext]

Here are examples of this format:

dotnet-runtime-2.0.4-macos.10.12-x64.pkg # Mac runtime installer dotnet-sdk-2.0.4-win10-x64.exe # Windows SDK installer dotnet-sdk-2.0.4-linux-x64.tar.gz # Portable Linux binary archive #Ubuntu file set needed for the SDK dotnet-hostfxr-2.0.4-ubuntu.16.04-x64.deb # Host policy dotnet-host-2.0.4-ubuntu.16.04-x64.deb # Host / muxer dotnet-runtime-2.0.4-ubuntu.16.04-x64.deb # runtime dotnet-sdk-2.0.4-ubuntu.16.04-x64.deb # SDK tools 

Note: See the Linux packages section below for Linux package naming conventions.

Intermediate installer filenames

There are a number of intermediate packages created which are then combined into the final installer bundle. The intermediate filenames will also need to be adjusted for consistency and to resolve final bundle name conflicts.

The scheme below appends -internal to the component portion of filenames which are not meant for direct customer usage but are part of final bundle composition.

Improvements relative to .NET Core 1.x:

1. Readability is greatly enhanced by ordering the information from broad to specific, from left to right: product->component->version->platform.
2. The runtime package name includes 'runtime'.

Open issue: Can the host and fxr be included in the same package?

Installer UI string changes

.NET Core installers for Windows and Mac will clearly describe their contents, as you can see in the following examples.

Preview releases will differ only slightly:

Preview releases are typical of the first patch release, so the .4 patch in the prior example has been changed to .0 for this preview example.

In the .NET Core 1.1 release, we decided to include two runtimes in the SDK. If we choose to do that again, in the .NET Core 2.1 release, for example, the installer UX will look like the following (only the SDK is shown since the Runtime isn't relevant):

It is also possible that we need to fix the .NET Core SDK but re-ship an existing runtime. In that case, we would bump the SDK version (for example, to 2.1.2) and then have the Runtime catch up the next time it shipped (for example, both the Runtime and SDK ship the following time as 2.1.3).

Improvements relative to .NET Core 1.x:

• Installer UI will be consistent across platforms.
• Installer UI will include complete information for SDK and Runtime versions.

Linux packages

Currently the only native Linux installers we produce are for Ubuntu but additional installers are planned. Linux package managers support chaining rather than embedding. Because of this, we release discrete packages for each component on Ubuntu which are chained by a controlling package referenced at install time. Using the name format proposed above:

dotnet-sdk # Latest stable version of the SDK dotnet-sdk-2.0 # Latest stable version of the 2.0 SDK dotnet-runtime # Latest stable version of the runtime dotnet-runtime-2.0 # Latest stable version of the 2.0 runtime 

Developers on Ubuntu would install either the SDK or runtime package, depending on their needs. The following command would install the latest SDK, a specific SDK version and a specific runtime version, respectively:

• apt-get install dotnet-sdk-2.0
• apt-get install dotnet-runtime-2.0

Viewing the results in the package manager after installation will show something similar to the following after installing the SDK.

dotnet-sdk-2.0/xenial,now 2.0.0-1 amd64 [installed] dotnet-host/xenial,now 2.0.0 amd64 [installed,automatic] dotnet-hostfxr-2.0.0/xenial,now 2.0.0-1 amd64 [installed,automatic] dotnet-runtime-2.0.0/xenial,now 2.0.0-1 amd64 [installed,automatic] 

For other Linux distros, we will make choices that satisfy the given distro requirements while aligning as closely as possible with the component naming and versioning that is defined above.

Improvements relative to .NET Core 1.x:

• Provide two entry-point versioned packages, one for the SDK and one for the runtime.
• Enables update functionality using Linux package managers where native installers are used.
• Provide a top-level dotnet package, which points to the latest SDK version. This is the same as latest in Docker.
• Rename sharedframework package to runtime.

Docker

A general Docker tag naming convention is to place the version number before the component name. This convention may continue to be utilized. The current tags include only the Runtime version as follows.

• 1.0.8-runtime
• 1.0.8-sdk
• 2.0.4-runtime
• 2.0.4-sdk
• 2.1.1-runtime
• 2.1.1-sdk

The SDK tags should be updated to represent the SDK version rather than Runtime.

It is also possible that we need to fix the .NET Core Tools but re-ship an existing runtime. In that case, we would bump the SDK version (for example, to 2.1.2) and then have the Runtime catch up the next time it shipped (for example, both the Runtime and SDK ship the following time as 2.1.3).

Meta-Packages

The NETStandard.Library and Microsoft.NETCore.App meta-packages are no longer an important developer concern in .NET Core 2.0. ASP.NET Core Meta-packages will continue to be a relevant part of the developer experience. They will match the ASP.NET Core version, as they have done in .NET Core 1.x.

The rationale for this change will be provided separately.

NuGet Packages

.NET Core will no longer be distributed via NuGet (for example, the System.Runtime package). ASP.NET Core will continue to be delivered as packages, and will continue to version like it was in .NET Core 1.x.

The rationale for this change will be provided separately.

.NET Core Websites and Documentation

The .NET Core websites and documentation have the important responsibility of making these releases easy to understand. It should be obvious what to download.

The .NET Core download page is the key page to improve. Changes that are made there will be straightforward to replicate on other pages. The SDK and Runtime views are quite different, so will be treated separately.

Runtime

See: https://www.microsoft.com/net/download/core#/runtime

• The 3 part version is displayed. No change needed.
• LTS and Current are clearly described. No change needed.
• These is no link to release notes for the runtimes. Release note links should be provided.

SDK

See: https://www.microsoft.com/net/download/core#/sdk

• No version is provided for the SDK. The 3 part version should be displayed.
• Runtime versions are provided instead of the SDK version. These should be removed. The expectation should be that SDK and Runtime versions generally match.
• These is no link to release notes for SDK. A release note link should be provided that describes everything about the SDK, most notably which runtime(s) is included.

General

• fwlinks are used for all downloads. These should be changed to the actual download links. It is now appropriate to link to those files directly given the more intuitive link format.
• Consider removing the word "download", which appears many times. If we need an extra word, consider "installer" and "archive", where appropriate.

Credit

Initial proposal was written by @leecow, @DamianEdwards, @richlander

Appendix:

.NET Core 1.x file name and versioning format

.NET Core 1.x uses the following format for file distributions:

[product]-[component]-[platform]-[arch].[major].[minor].[patch]-[previewN]-[optional build #].[file ext]

Here are examples of this format:

dotnet-osx-x64.1.0.4.pkg # Mac runtime installer dotnet-dev-win-x64.1.0.1.exe # Windows SDK installer dotnet-dev-fedora.24-x64.1.0.1.tar.gz # Fedora 24 binary archive #Ubuntu file set needed for the SDK dotnet-host-ubuntu.16.04-x64.1.0.1.deb # Host / muxer dotnet-hostfxr-ubuntu.16.04-x64.1.0.1.deb # Host policy dotnet-sharedframework-ubuntu.16.04-x64.1.0.4.deb # Runtime dotnet-sdk-ubuntu.16.04-x64.1.0.1.deb # SDK 

This format has the following challenges:

1. It's difficult to easily scan the component / version pair
2. Nothing is obviously presented as a Runtime component
3. Naming inconsistency between sdk and dev packages across platforms.