Reorganize version articles #6453

BillWagner · 2018-07-13T16:36:12Z

Picking up the work done in #6081 to carry it to completion.

This fixes several issues:
Fixes #4241
Fixes #4352
Fixes #5304
Fixes #6249

Internal review link Include pages under this TOC node.

Notes for reviewers:

@jcouv @cartermp I've updated the language versions in versions-history.md based on previous comments.

@leecow I've updated the discussion on support to point to the official page and removed the duplicate information.

@leecow The uinstall instructions for Linux and MacOS were based on your earlier information, and working on my machines. apt-get is not installed by default on MacOS, so I explained how to remove versions manually.

Moving those changes to a new branch and PR.

switching branches

BillWagner · 2018-07-26T20:34:53Z

docs/core/versions/version-history.md

+.. Footnote for VB versions aligning to Visauls Studio
+
+
+| Date       | .NET Core SDK(4) | .NET Core Runtimes | Contains C# | Contains VB | Notes |


@cartermp Do you know where I can get information for an F# column for this table?

We don't have this listed anywhere I think, but the F# language version for all of these is 4.1.

Starting with SDK 2.1.400, it will be F# 4.5.

BillWagner · 2018-07-26T20:41:37Z

docs/core/versions/version-history.md

+.. Footnote for VB versions aligning to Visauls Studio
+
+
+| Date       | .NET Core SDK(4) | .NET Core Runtimes | Contains C# | Contains VB | Notes |


@danroth27 Do you know where I can get source for an ASP.NET Core runtime for this table?

Remaining tasks: - [ ] Finish table in version-history - [ ] write uinstall instructions, and guidance on which versions you need - [ ] update LTS information

Moving to Mac to finish uninstall

leecow · 2018-07-27T19:25:57Z

@BillWagner - The uninstall instructions for Linux are a combination wildly incomplete and just plain wrong. Schedule some time so we can discuss.

BillWagner · 2018-07-31T16:47:33Z

@leecow I updated the Linux instructions after our discussion. I think they are much better now. Can you review again?

leecow

Thanks Bill, couple of notes and comments to address.

leecow · 2018-07-31T17:03:28Z

docs/core/versions/remove-runtime-sdk-versions.md

+
+```console
+$ dotnet --list-sdks
+1.0.1 [/usr/local/share/dotnet/sdk]


These are all Mac locations. Linux installs will be /usr/share/dotnet.

leecow · 2018-07-31T17:05:38Z

docs/core/versions/remove-runtime-sdk-versions.md

+If you installed .NET Core using a package manager, you use that same package manager to uninstall .NET SDK or runtime. .NET Core installations support most popular package managers. Consult the documentation for your distribution's package manager for the precise syntax on your environment:
+
+- [apt-get](https://wiki.debian.org/apt-get) is used by Debian based systems, including Ubuntu.
+- [yum](http://yum.baseurl.org/wiki/YumCommands) is used on Fedora, SUSE Linux Enterprise System (SLES), CentOS, and Oracle Linux.


SLES uses zypper by default

Also, it's more idiomatic to reference man pages than web sites. eg dnf(8)

I updated all the references to the online man pages. LMK if you have better links for any of them.

leecow · 2018-07-31T17:15:23Z

docs/core/versions/remove-runtime-sdk-versions.md

+
+In almost all cases, the command to remove a package is `remove`.
+
+The package name for the .NET Core SDK installation for most package managers is `dotnet-sdk`, followed by the version number. For example, the .NET Core SDK version 2.1 is the package `dotnet-sdk-2.1`.


This versioning scheme is only valid for 2.1+ for the runtime and 2.1.300+ for the SDK. Older versions require the entire version number, eg dotnet-sdk-2.1.200.

JRAlexander

Looks good, @BillWagner! Just a few small changes and then you should be ready to rock.

JRAlexander · 2018-07-31T22:33:32Z

docs/core/versions/remove-runtime-sdk-versions.md

@@ -0,0 +1,186 @@
+---
+title: How to remove .NET runtime and SDK
+description: Instructions for removing the .NET Core Runtime and SDK components on Windows, Mac, and Linx


JRAlexander · 2018-07-31T22:34:50Z

docs/core/versions/remove-runtime-sdk-versions.md

+
+Over time, as you install updated versions of the .NET Core runtime and SDK, you may want to remove outdated versions of .NET Core. Removing older versions of the runtime may change the runtime chosen to run shared framework applications, as detailed in the article on [.NET Core version selection](selection.md).
+
+The .NET CLI has options you can use to list the versions of the SDK and runtime that are installed on your machine.  Use [`dotnet --list-sdks`](../tools/dotnet.md#options) to see the list of SDKs installed on your machine. Use [`dotnet --list-runtimes`](../tools/dotnet.md#options) to see the list of runtimes installed on your machine. The following text shows typical output for Windows or unix:


unix: -> should this be Linux to match tab heading and output below?

JRAlexander · 2018-07-31T22:40:51Z

docs/core/versions/remove-runtime-sdk-versions.md

+
+In almost all cases, the command to remove a package is `remove`.
+
+The package name for the .NET Core SDK installation for most package managers is `dotnet-sdk`, followed by the version number. Starting with the version 2.1.300 of the .NET Core SDK and version `2.1` of the runtime, only the major and minor version numbers are necessary: for example, the .NET Core SDK version 2.1.300 can be referenced as the package `dotnet-sdk-2.1`. Prior versions require the entire version string: for example, `dotnet-sdk-21.200` would be required for version 2.1.200 of the .NET Core SDK.


This should be "dotnet-sdk-2.1.200"

JRAlexander

Looks good, one more small spelling thing and we should be good to go!

JRAlexander · 2018-08-01T12:21:37Z

docs/core/versions/remove-runtime-sdk-versions.md

@@ -9,7 +9,7 @@ ms.author: wiwagn

 Over time, as you install updated versions of the .NET Core runtime and SDK, you may want to remove outdated versions of .NET Core. Removing older versions of the runtime may change the runtime chosen to run shared framework applications, as detailed in the article on [.NET Core version selection](selection.md).

-The .NET CLI has options you can use to list the versions of the SDK and runtime that are installed on your machine.  Use [`dotnet --list-sdks`](../tools/dotnet.md#options) to see the list of SDKs installed on your machine. Use [`dotnet --list-runtimes`](../tools/dotnet.md#options) to see the list of runtimes installed on your machine. The following text shows typical output for Windows or unix:
+The .NET CLI has options you can use to list the versions of the SDK and runtime that are installed on your machine.  Use [`dotnet --list-sdks`](../tools/dotnet.md#options) to see the list of SDKs installed on your machine. Use [`dotnet --list-runtimes`](../tools/dotnet.md#options) to see the list of runtimes installed on your machine. The following text shows typical output for Windows, MacOS, or Linix:


JRAlexander · 2018-08-01T14:45:34Z

Looks great, @BillWagner! at your convenience!!!

mairaw · 2018-08-01T17:05:07Z

docs/core/tutorials/metapackages.md

@@ -0,0 +1,14 @@
+


this is missing metadata and title. etc.

This file was supposed to be removed (The information from it is now in the versions/index.md file.)

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.

BillWagner · 2018-08-03T15:09:25Z

@mairaw Can you give the last commit one final review? It's larger than I'd like to merge without another set of 👀

BillWagner · 2018-08-03T15:17:16Z

I think this got caught between PR merges. closing and reopening to build.

mairaw · 2018-08-03T20:30:50Z

Will do @BillWagner! Need just to grab a bite first 😄

mairaw

@BillWagner this looks great! Thanks for taking this on. I did leave some comments for you to consider before merging.

mairaw · 2018-08-03T21:32:48Z

docs/core/versions/index.md

 ---
 # .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 that contains the tools you need to develop applications. .NET Core SDKs are designed to work with any previous version of the .NET Core Runtime. This article explains the runtime and the SDK version strategy. An explanation of version numbers for .NET Standard can be found in the article introducing [.NET Standard](../../standard/net-standard.md#net-implementation-support).


wondering if that contains the tools would be better to say , which contains the tools to make it more explicit that it refers to the SDK

mairaw · 2018-08-03T21:33:44Z

docs/core/versions/index.md


-All web site descriptions and UI strings in the installers are kept consistent, accurate, and simple. The following table shows some examples:
+The .NET Core SDK does not follow semantic versioning. The .NET Core SDK releases faster and its versions, must communicate both the aligned runtime and the  SDK's own minor and patch releases. The first two positions of the .NET Core SDK version are locked to the .NET Core Runtime it released with. Each version of the SDK can create applications for this runtime or any lower version.


nit: does not follow -> doesn't follow (other contractions in the text could be made for will not, is not, etc.)

no comma between its versions and must communicate

remove extra space between the & SDK's

mairaw · 2018-08-03T21:35:21Z

docs/core/versions/index.md

-| :--       | :--                                   | :--                        | :--                                             |
-| SDK       | .NET Core 2.0 SDK (x64) Installer     | .NET Core 2.0.4 SDK        | .NET Core 2.0.4 Tools + .NET Core 2.0.4 Runtime |
-| Runtime   | .NET Core 2.0 Runtime (x64) Installer | .NET Core 2.0.4 Runtime    | .NET Core 2.0.4 Runtime                         |
+The third position of the SDK version number communicates both the minor and patch number. The minor version is multiplied by 100 (starting at 100). The final two digits represent the patch number. For example, the release of .NET Core 2.2 may create releases like the following table:


starting at 100 or at 1?

mairaw · 2018-08-03T21:38:35Z

docs/core/versions/index.md

-| :--       | :--                                             | :--                               | :--                                                                 |
-| SDK       | .NET Core 2.0 Preview 1 SDK (x64) Installer     | .NET Core 2.0.0 Preview 1 SDK     | .NET Core 2.0.0 Preview 1 Tools + .NET Core 2.0.0 Preview 1 Runtime |
-| Runtime   | .NET Core 2.0 Preview 1 Runtime (x64) Installer | .NET Core 2.0.0 Preview 1 Runtime | .NET Core 2.0.0 Preview 1 Runtime                                   |
+(*) This chart uses a future 2.2 .NET Core Runtime as the example because a historic artifact meant the first SDK for .NET Core 2.1 is 2.1.300. For more information, See the [history of .NET Core versioning](version-history.md).


escape the asterisk

mairaw · 2018-08-03T21:39:16Z

docs/core/versions/index.md


-### Shipping a minor release
+.NET Standard consists of a .net reference assembly. There are multiple implementations specific to each platform. The reference assembly 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.


.net -> .NET

The reference assembly contains the definition of .NET Standard. -> should you mention version here as well? The assembly will contain the definition for each version, right?

LInk to the .NET standard topic for more info?

mairaw · 2018-08-03T21:47:15Z

includes/net-standard-table.md

@@ -1,7 +1,7 @@
 | .NET Standard              | [1.0] | [1.1]  | [1.2] | [1.3] | [1.4] | [1.5]      | [1.6]      | [2.0]      |
 |----------------------------|-------|--------|-------|-------|-------|------------|------------|------------|
 | .NET Core                  | 1.0   | 1.0    | 1.0   | 1.0   | 1.0   | 1.0        | 1.0        | 2.0        |
-| .NET Framework <sup>1</sup>| 4.5   | 4.5    | 4.5.1 | 4.6   | 4.6.1 | 4.6.1      | 4.6.1      | 4.6.1      |
+| .NET Framework <sup>1</sup>| 4.5   | 4.5    | 4.5.1 | 4.6   | 4.6.1 | 4.6.1      | 4.6.1      | 4.7.2      |


has this changed? https://github.com/dotnet/standard/blob/master/docs/versions.md still lists 4.6.1

I was going by this comment: #5915 (comment) @terrajobst Thoughts? 4.7.2 came out with the April Window 10 update.

Dropped #5915 from the list of issues addressed by this PR, and reverted this change.

mairaw · 2018-08-03T21:52:09Z

docs/core/versions/remove-runtime-sdk-versions.md

+apt-get remove dotnet-host
+```
+
+Note that there is no version attached to `dotnet-host`


missing punctuation

mairaw · 2018-08-03T21:52:31Z

docs/core/versions/remove-runtime-sdk-versions.md

+
+Note that there is no version attached to `dotnet-host`
+
+If you installed using a tarball, you must remove .NET Core using the manual method:


period instead of colon here?

mairaw · 2018-08-03T21:54:09Z

docs/core/versions/remove-runtime-sdk-versions.md

+
+The parent directories for the SDK and runtime are listed in the output from the `dotnet --list-sdks` and `dotnet --list-runtimes` command, as shown in the earlier table.
+
+Starting with .NET Core 2.1, there is no need to uninstall the .NET Core SDK when upgrading it using a package manager. The package manager `update` or `refresh` commands will automatically remove the older version upon the successful installation of a newer version.


I think you need to end the tab section with ---, no?

mairaw · 2018-08-03T21:56:15Z

docs/core/versions/version-history.md

+
+# NET Core version history
+
+Version numbers for .NET Core are challenging because .NET Core SDK and .NET Core Runtime release on different cadences. The different cadences means a choice to do only two of the following three things:


the last sentence is a bit weird in the sense that this is a choice for the team.

cadences means -> cadences mean

BillWagner added the WIP label Jul 13, 2018

BillWagner requested a review from mairaw as a code owner July 13, 2018 16:36

This was referenced Jul 13, 2018

WIP: Reorganize version topic #6081

Closed

What is meant by - "Other content in installer" ? #6249

Closed

KathleenDollard and others added 3 commits July 26, 2018 11:40

Reorganize version topic

2ea44cf

update per feedback on PR dotnet#6081

bda6bae

Moving those changes to a new branch and PR.

interim checkin

962ed86

switching branches

BillWagner force-pushed the reorganize-version-articles branch from 03a22a0 to 962ed86 Compare July 26, 2018 15:40

BillWagner commented Jul 26, 2018

View reviewed changes

BillWagner and others added 5 commits July 26, 2018 17:13

Next draft

56f9936

Remaining tasks: - [ ] Finish table in version-history - [ ] write uinstall instructions, and guidance on which versions you need - [ ] update LTS information

write uninstall

402f716

Moving to Mac to finish uninstall

Add unix and linux uinstall instructions.

598c421

proofread

9fac058

fix a tab error

7ed62e7

BillWagner changed the title ~~[WIP] Reorganize version articles~~ Reorganize version articles Jul 27, 2018

BillWagner removed the WIP label Jul 27, 2018

BillWagner added the WIP label Jul 27, 2018

update Linux uninstall instructions

e49242b

BillWagner removed the WIP label Jul 31, 2018

leecow requested changes Jul 31, 2018

View reviewed changes

respond to feedback on Linux uninstall

4cd46c2

JRAlexander suggested changes Jul 31, 2018

View reviewed changes

respond to content feedback.

cf48068

JRAlexander suggested changes Aug 1, 2018

View reviewed changes

typo

f559e35

JRAlexander approved these changes Aug 1, 2018

View reviewed changes

BillWagner added 2 commits August 1, 2018 10:56

branding: macOS is the official capitalization

fadb4ce

final proofread

6b44203

mairaw reviewed Aug 1, 2018

View reviewed changes

BillWagner closed this Aug 3, 2018

BillWagner reopened this Aug 3, 2018

mairaw approved these changes Aug 3, 2018

View reviewed changes

BillWagner added 2 commits August 4, 2018 14:17

respond to feedback

fb86771

revert framework cell for .NET standard 2.0

5fbfc14

BillWagner merged commit 519bdc7 into dotnet:master Aug 7, 2018

BillWagner deleted the reorganize-version-articles branch September 7, 2018 17:22

		.. Footnote for VB versions aligning to Visauls Studio


		\| Date \| .NET Core SDK(4) \| .NET Core Runtimes \| Contains C# \| Contains VB \| Notes \|


		In almost all cases, the command to remove a package is `remove`.

		The package name for the .NET Core SDK installation for most package managers is `dotnet-sdk`, followed by the version number. For example, the .NET Core SDK version 2.1 is the package `dotnet-sdk-2.1`.


		Over time, as you install updated versions of the .NET Core runtime and SDK, you may want to remove outdated versions of .NET Core. Removing older versions of the runtime may change the runtime chosen to run shared framework applications, as detailed in the article on [.NET Core version selection](selection.md).

		The .NET CLI has options you can use to list the versions of the SDK and runtime that are installed on your machine. Use [`dotnet --list-sdks`](../tools/dotnet.md#options) to see the list of SDKs installed on your machine. Use [`dotnet --list-runtimes`](../tools/dotnet.md#options) to see the list of runtimes installed on your machine. The following text shows typical output for Windows or unix:


		All web site descriptions and UI strings in the installers are kept consistent, accurate, and simple. The following table shows some examples:
		The .NET Core SDK does not follow semantic versioning. The .NET Core SDK releases faster and its versions, must communicate both the aligned runtime and the SDK's own minor and patch releases. The first two positions of the .NET Core SDK version are locked to the .NET Core Runtime it released with. Each version of the SDK can create applications for this runtime or any lower version.


		### Shipping a minor release
		.NET Standard consists of a .net reference assembly. There are multiple implementations specific to each platform. The reference assembly 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.


		Note that there is no version attached to `dotnet-host`

		If you installed using a tarball, you must remove .NET Core using the manual method:


		The parent directories for the SDK and runtime are listed in the output from the `dotnet --list-sdks` and `dotnet --list-runtimes` command, as shown in the earlier table.

		Starting with .NET Core 2.1, there is no need to uninstall the .NET Core SDK when upgrading it using a package manager. The package manager `update` or `refresh` commands will automatically remove the older version upon the successful installation of a newer version.


		# NET Core version history

		Version numbers for .NET Core are challenging because .NET Core SDK and .NET Core Runtime release on different cadences. The different cadences means a choice to do only two of the following three things:

Reorganize version articles #6453

Reorganize version articles #6453

Conversation

BillWagner commented Jul 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leecow commented Jul 27, 2018

BillWagner commented Jul 31, 2018

leecow left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JRAlexander left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JRAlexander left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JRAlexander commented Aug 1, 2018

mairaw Aug 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BillWagner commented Aug 3, 2018

BillWagner commented Aug 3, 2018

mairaw commented Aug 3, 2018 • edited Loading

mairaw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BillWagner commented Jul 13, 2018 •

edited

Loading

mairaw Aug 1, 2018 •

edited

Loading

mairaw commented Aug 3, 2018 •

edited

Loading