.NET Core 2+ Naming and Versioning #43524
Comments
What exactly does this mean? Are the |
|
Also wondering what that means. Is that the actual corefx libs or just the runtime and native bits? |
|
What it really means is that you will not have to explicitly reference any packages by default to build a .NET Core application. It also means that the 100+ individual packages will not be available on NuGet. There will be a single package for the .NET Core Platform on NuGet that will be implicitly referenced when you target netcore2.0 in your project. |
He means, starting with .NET Core 2.0. No existing packages on nuget.org will be harmed in the filming of this movie.
That's a good question. @Petermarcu and @terrajobst would be better to answer that one. In general, I did a bad thing by writing about this part of the plan in a vague and haphazard way. Sorry! @terrajobst will do a proper write-up of this soon. |
|
As @tmds pointed out, Linux packaging was discussed and agreed on by just about every relevant party in https://github.com/dotnet/core-setup/issues/1599 and RH/MS meetings. I would like to suggest sticking to the resulting documents on Microsoft's side of packages as well, at least to some degree... |
|
I have two questions:
(I don't know if I've gotten all these right.)
|
|
@adamralph I'm sure that someone else could explain it better, but preview is neither alpha, nor beta, nor release candidate. It's a preview... |
I assume this would also hold true for the meta-packages when targeting |
|
Yes. |
|
There will also still be runtime.* packages that are hidden behind the TargetFramework and only used to build self-contained apps. They will be one flat package that contains the implementation of the TargetFramework for a given RuntimeIdentifier. |
And therein lies the problem. Most people don't know what "preview" means in terms of release quality, other than "not RTM". There is a widely recognised naming practice for "not RTM" packages, which is alpha, beta, RC. I'm proposing adopting that and dropping the "preview" approach. |
|
@Thealexbarney We just chatted. The runtime.* packages will still be delivered via NuGet. This is needed to make this scenario work (publishing self-contained apps for another OS), for example: https://github.com/dotnet/dotnet-docker-samples/tree/master/dotnetapp-selfcontained. |
We would like to do that, but we have a fundamental challenge with it. We pick two things significantly in advance of shipping: the pre-release moniker and the ship-date. We are often targeting a Microsoft conference, typically Build or Connect and those dates don't move. We need the moniker in place for the engineering system to work, including branch names. In the past, we chose |
|
@richlander 👍 thanks for the explanation. It's good to know that you have the "standard" pre-release monikers in mind. |
New file name structure for the runtime and the CLI per: https://github.com/dotnet/designs/issues/2 1. Branding changes 2. renaming of assets
New file name structure for the runtime and the CLI per: https://github.com/dotnet/designs/issues/2 The renaming of assets, therefore the dotnet installation scripts must change to accommodate. Trivial: "Write-Host" should be "Write-Output"
|
Are we sure
|
|
@eerhardt discussed in: https://github.com/dotnet/core-setup/issues/1599 (A grumpy comment: I still don't like how all our effort in the above ticket is ignored by Microsoft. Not an open-source-way.) |
|
@richlander can you also include guidelines for 'stores' Per @bleroy 's comment on dotnet/aspnetcore#2033, Microsoft plans to put the ASP.NET Core store in the sdk package:
|
|
@eerhardt also I forgot to mention, the |
|
Much welcome improvement. One suggestion I have is to make sure you use # arch name
$ uname -m
x86_64
# OS name
$ uname -s
LinuxThen I can have something portable like: $ curl -o https://host/path/dotnet-sdk-$(VERSION)-$(uname -s)-$(uname -m).tar.gz |
|
Thanks for the feedback @kontsevoy! Another change which we've made in .NET Core 2 which I need to account for in this document is 'portable' Linux builds. This will take care of |
Building illink with a machine-wide install of the SDK was causing problems because the SDK resolver looks in global locations and rolls forward to the newest available SDK. (The behavior is described in https://github.com/dotnet/designs/issues/2.) We want to use a repo-local SDK to build illink for reproducibility, so we use a global.json to prevent roll-forward. Testing shows that this results in the local SDK being preferred when a matching version is also available machine-wide. Roll-forward behavior was causing extra validation logic in the new SDK to be enabled. This logic was tripping over a workaround we have for nuget restore issues. We will need to investigate this interaction when we next update the repo-local SDK.
Building illink with a machine-wide install of the SDK was causing problems because the SDK resolver looks in global locations and rolls forward to the newest available SDK. (The behavior is described in https://github.com/dotnet/designs/issues/2.) We want to use a repo-local SDK to build illink for reproducibility, so we use a global.json to prevent roll-forward. Testing shows that this results in the local SDK being preferred when a matching version is also available machine-wide. Roll-forward behavior was causing extra validation logic in the new SDK to be enabled. This logic was tripping over a workaround we have for nuget restore issues. We will need to investigate this interaction when we next update the repo-local SDK.
|
Could runtime vs sdk versions be revisited? When talking it over with devs, I constantly need to explain the difference between the SDK and Runtime versions. The recent move from 2.0.* to 2.1.* with newer MSBuild + Roslyn versions confused a lot of ppl (e.g. .NET Core 2.1 requires SDK 2.2.*) as well as how patch versions are handled. There was a short period where a branch of the CLI produced I see the following goals in versioning:
The only problem that this introduces is that the major versions looks similar to the .NET Core runtime version. They have all been 1.* or 2.*. Proposed solutions:
|
|
@dasMulli's suggestion addresses things that have been bugging me. |
|
fyi: new proposal for CLI version numbers is in PR by @KathleenDollard: dotnet/designs#29 |
|
This is replaced with @KathleenDollard: dotnet/designs#29 I apologize for the delay in updating/closing this issue. |
|
Re-opening as this document covers significantly more ground than dotnet/designs#29. CLI section of this post can be updated as appropriate. |
|
@leecow @KathleenDollard @richlander I'm fine with this so long this issue gets resolved by a PR that is merged. This repo isn't meant to have designs sitting here as issues -- the designs are to be checked in and issues are to be closed, just like regular source code. So who is on the hook for this? |
|
Seems like the 'doc' form probably should live on /core. I'll aggregate and PR. |
|
Many of these things were implemented already or no longer make sense because they have been superseded with other ideas. In any case, this doc is now very stale. |
Dotnet-GitSync-Bot
added
area-Meta
untriaged
ghost
locked as resolved and limited conversation to collaborators
.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
.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:
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
-internalto 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:
product->component->version->platform.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
.4patch in the prior example has been changed to.0for 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):
.NET Core Runtime 2.0.6
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:
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:
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.0apt-get install dotnet-runtime-2.0Viewing the results in the package manager after installation will show something similar to the following after installing the SDK.
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:
dotnetpackage, which points to the latest SDK version. This is the same aslatestin Docker.sharedframeworkpackage toruntime.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-runtime1.0.8-sdk2.0.4-runtime2.0.4-sdk2.1.1-runtime2.1.1-sdkThe 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
SDK
See: https://www.microsoft.com/net/download/core#/sdk
General
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:
This format has the following challenges:
The text was updated successfully, but these errors were encountered: