WIP: Reorganize version topic #6081
Conversation
KathleenDollard
changed the title
|
@KathleenDollard can you fix the merge conflicts? Reviewing other changes now... |
|
|
||
| ### Shipping a patch release | ||
|
|
||
| After shipping a major release of .NET Core, such as version 2.0.0, patch-level changes are made to .NET Core libraries to fix bugs and improve performance and reliability. That means that no new APIs are introduced. The various metapackages are updated to reference the updated .NET Core library packages. The metapackages are versioned as patch updates (`MAJOR.MINOR.PATCH`). Target frameworks are never updated as part of patch releases. A new .NET Core distribution is released with a version number that matches that of the `Microsoft.NETCore.App` metapackage. |
There was a problem hiding this comment.
The paragraph implies that only major versions are patched. Wouldn't we also apply patches to minor versions (such as 2.1.0)?
|
|
||
| ### Target frameworks | ||
|
|
||
| Target framework versions are updated when new APIs are added. They have no concept of patch version, since they represent API shape and not implementation concerns. Major and minor versioning follows the SemVer rules specified earlier, and coincides with the `MAJOR` and `MINOR` numbers of the .NET Core distributions that implement them. |
There was a problem hiding this comment.
"of the .NET Core distributions that implement them." Developers can specific .NET Standard, such as netstandard2.0 as the TFM, so it's not strictly a .NET core concept, right?
| @@ -0,0 +1,14 @@ | |||
|
|
|||
There was a problem hiding this comment.
We need to add the metadata block here (and all other files in this PR)
|
|
||
| Target framework versions are updated when new APIs are added. They have no concept of patch version, since they represent API shape and not implementation concerns. Major and minor versioning follows the SemVer rules specified earlier, and coincides with the `MAJOR` and `MINOR` numbers of the .NET Core distributions that implement them. | ||
|
|
||
| ## Versioning in practice |
There was a problem hiding this comment.
Should this just be deleted? I'm not sure what readers would get from this paragraph.
There was a problem hiding this comment.
This entire file is text that I thought didn't have value in the context of this overall topic (version). I left this file temporarily so that other folks could see what I trashed since diffs are pretty hopeless with this much moving around.
| @@ -7,130 +7,69 @@ ms.date: 02/13/2018 | |||
| --- | |||
| # .NET Core versioning | |||
|
|
|||
| .NET Core is made of [NuGet packages](../packages.md), tools, and frameworks that are distributed as a unit. Each of these platform layers can be versioned separately, enabling better agility. While there is significant versioning flexibility in that regard, there's also a desire to version the platform as a unit to make the product easier to understand. | |||
| .NET Core refers to the .NET Core Runtime and the .NET Core SDK which contains the tools you need to develop applications. A version of the .NET Core Runtime. .NET Core SDKs are designed to work with any previous version of the .NET Core Runtime. | |||
There was a problem hiding this comment.
Something is missing in the 2nd sentence. "A version of the .NET Core Runtime".
| Evaluating [releases.json](https://github.com/dotnet/core/blob/master/release-notes/releases.json) yields the following. [[Who can help fill in the missing C# versions?]] | ||
|
|
||
| | Date | .NET Core SDK(4) | .NET Core Runtimes | Contains C# | Contains VB | Notes | | ||
| |------------|------------------|--------------------|-------------|-------------|-------| |
There was a problem hiding this comment.
This table also means this PR will fix #4154
| @@ -0,0 +1,15 @@ | |||
|
|
|||
| ### Docker | |||
There was a problem hiding this comment.
This section reads more like a spec for future development than a doc. It's mostly future tense and discusses possibilities.
|
|
||
| # Versioning .NET Standard | ||
|
|
||
| .NET Standard consists of a reference library and implementations specific to each platform. The reference library contains the definition of .NET Standard. Each implementation fulfills the .NET Standard contract on the specific platform. .NET Standard usually refers to the reference library, and the implementation is detail of the corresponding runtime. |
There was a problem hiding this comment.
"reference library" is a troubling term. It could be read (mistakenly) as a reference implementation. I'd add a clarifying sentence that the .NET Standard reference library is a ".NET Reference Assembly", meaning there is API definitions but no implementation.
| |-----------|---------------| | ||
| | 1.0 | up to 1.6 | | ||
| | 2.0 | up to 2.0 | | ||
| | 2.1 | up to 2.1 | |
There was a problem hiding this comment.
This table disagrees with the paragraph above.
|
|
||
| The implementations on each runtime may version, but this would normally be part of the runtime release, and thus not evident to the programmers using .NET Standard on that platform. | ||
|
|
||
| There is no real coupling between .NET Standard versions and .NET Core versions: .NET Core 2.0 happens to implement .NET Standard 2.0, but .NET Core 2.1 also implements .NET Standard 2.0. .NET Core will ship new APIs not yet included in .NET Standard. .NET Standard is also a concept that applies to other targets, such as .NET Framework or Mono, even if its inception happened to coincide with that of .NET Core. If .NET Standard 2.1 ships, .NET Core 2.1 will not support it. |
There was a problem hiding this comment.
I think this is confusing. Consider this:
"Each version of .NET Core implements a version of .NET standard. .NET Standard and .NET Core version independently. It's a coincidence that .NET Core 2.0 implements .NET Standard 2.0. .NET Core 2.1 also implements .NET Standard 2.0. .NET Core will support future versions of .NET Standard as they become available."
| | 2017-11-14 | 1.1.7 | 1.0.9, 1.1.6 | | | | | ||
| | 2018-03-13 | 1.1.8 | 1.0.10, 1.1.7 | | | | | ||
| | 2018-04-17 | 1.1.9 | 1.0.11, 1.1.8 | | | | | ||
| | 2017-08-14 | 2.0.0 | 2.0.0 | 7.1 | | | |
There was a problem hiding this comment.
Why is there no VB entry on the line for 2017-08-14 (which does list C# 7.1)? I'd expect VB 15.3 on that line (and following three lines).
Moving those changes to a new branch and PR.
|
Closing. These edits will be captured in #6453 |
Moving those changes to a new branch and PR.
* Reorganize version topic * update per feedback on PR #6081 Moving those changes to a new branch and PR. * interim checkin switching branches * Next draft Remaining tasks: - [ ] Finish table in version-history - [ ] write uinstall instructions, and guidance on which versions you need - [ ] update LTS information * write uninstall Moving to Mac to finish uninstall * Add unix and linux uinstall instructions. * proofread * fix a tab error * update Linux uninstall instructions * respond to feedback on Linux uninstall * respond to content feedback. * typo * branding: macOS is the official capitalization * final proofread * Final updates There are three updates in this commit: 1. Remove the metapackages.md file. It should have been removed earlier. 2. Remove the version history table, and link to the .NET Core downloads page. This page has been updated to include all the relevant information, and is updated with each release. Also, add a link to the archive page for information on older releases. 3. Update the net-standard-table to use Framework 4.7.2 for .NET Standard, and link to the download page for .NET Core 2.0 tooling for Visual Studio 2015. * respond to feedback * revert framework cell for .NET standard 2.0
Summary
Describe your changes here.
Fixes #Issue_Number (if available)