Reorganize version articles

docs/core/tutorials/metapackages.md

@@ -0,0 +1,14 @@
+
+### Shipping a patch release
+
+After shipping a major or minor 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.
+
+### Shipping a minor release
+
+After shipping a .NET Core version with an incremented `MAJOR` version number, new APIs are added to .NET Core libraries to enable new scenarios. The various metapackages are updated to reference the updated .NET Core library packages. The metapackages are versioned as patch updates with `MAJOR` and `MINOR` version numbers matching the new framework version. New target framework names with the new `MAJOR.MINOR` version are added to describe the new APIs (for example, `netcoreapp2.1`). A new .NET Core distribution is released with a matching version number to the `Microsoft.NETCore.App` metapackage.
+
+### Shipping a major release
+
+Every time a new major version of .NET Core ships, the `MAJOR` version number gets incremented, and the `MINOR` version number gets reset to zero. The new major version contains at least all the APIs that were added by minor releases after the previous major version. A new major version should enable important new scenarios, and it may also drop support for an older platform.
+
+The various metapackages are updated to reference the updated .NET Core library packages. The [`Microsoft.NETCore.App`](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage and the `netcore` target framework are versioned as a major update matching the `MAJOR` version number of the new release.

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
+ms.date: 07/28/2018
+author: billwagner
+ms.author: wiwagn
+---
+# How to remove the .NET Core Runtime and SDK
+
+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:
+
+# [Windows](#tab/Windows)
+
+```console
+C:\> dotnet --list-sdks
+2.1.200-preview-007474 [C:\Program Files\dotnet\sdk]
+2.1.200-preview-007480 [C:\Program Files\dotnet\sdk]
+2.1.200-preview-007509 [C:\Program Files\dotnet\sdk]
+2.1.200-preview-007570 [C:\Program Files\dotnet\sdk]
+2.1.200-preview-007576 [C:\Program Files\dotnet\sdk]
+2.1.200-preview-007587 [C:\Program Files\dotnet\sdk]
+2.1.200-preview-007589 [C:\Program Files\dotnet\sdk]
+2.1.200 [C:\Program Files\dotnet\sdk]
+2.1.201 [C:\Program Files\dotnet\sdk]
+2.1.202 [C:\Program Files\dotnet\sdk]
+2.1.300-preview2-008533 [C:\Program Files\dotnet\sdk]
+2.1.300 [C:\Program Files\dotnet\sdk]
+2.1.400-preview-009063 [C:\Program Files\dotnet\sdk]
+2.1.400-preview-009088 [C:\Program Files\dotnet\sdk]
+2.1.400-preview-009171 [C:\Program Files\dotnet\sdk]
+
+C:\> dotnet --list-runtimes
+Microsoft.AspNetCore.All 2.1.0-preview2-final [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.App 2.1.0-preview2-final [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
+Microsoft.NETCore.App 2.0.6 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.7 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.9 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.0-preview2-26406-04 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
+```
+
+# [Linux](#tab/Linux)
+
+```console
+$ dotnet --list-sdks
+1.0.1 [/usr/local/share/dotnet/sdk]
+1.0.4 [/usr/local/share/dotnet/sdk]
+2.0.0-preview1-005977 [/usr/local/share/dotnet/sdk]
+2.0.0-preview2-006497 [/usr/local/share/dotnet/sdk]
+2.0.0 [/usr/local/share/dotnet/sdk]
+2.1.4 [/usr/local/share/dotnet/sdk]
+2.1.300-preview2-008530 [/usr/local/share/dotnet/sdk]
+2.1.300 [/usr/local/share/dotnet/sdk]
+2.1.301 [/usr/local/share/dotnet/sdk]
+
+$ dotnet --list-runtimes
+Microsoft.AspNetCore.All 2.1.0-preview2-final [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.App 2.1.0-preview2-final [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.NETCore.App 1.0.4 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 1.0.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 1.1.1 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 1.1.2 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.0-preview1-002111-00 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.0-preview2-25407-01 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.0-preview2-26406-04 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+```
+
+# [MacOS](#tab/MacOS)
+
+```console
+$ dotnet --list-sdks
+1.0.1 [/usr/local/share/dotnet/sdk]
+1.0.4 [/usr/local/share/dotnet/sdk]
+2.0.0-preview1-005977 [/usr/local/share/dotnet/sdk]
+2.0.0-preview2-006497 [/usr/local/share/dotnet/sdk]
+2.0.0 [/usr/local/share/dotnet/sdk]
+2.1.4 [/usr/local/share/dotnet/sdk]
+2.1.300-preview2-008530 [/usr/local/share/dotnet/sdk]
+2.1.300 [/usr/local/share/dotnet/sdk]
+2.1.301 [/usr/local/share/dotnet/sdk]
+
+$ dotnet --list-runtimes
+Microsoft.AspNetCore.All 2.1.0-preview2-final [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.All 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All]
+Microsoft.AspNetCore.App 2.1.0-preview2-final [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.AspNetCore.App 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App]
+Microsoft.NETCore.App 1.0.4 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 1.0.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 1.1.1 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 1.1.2 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.0-preview1-002111-00 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.0-preview2-25407-01 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.0.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.0-preview2-26406-04 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+Microsoft.NETCore.App 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
+```
+
+***
+
+## Uninstalling .NET Core
+
+# [Windows](#tab/Windows)
+
+.NET Core uses the Windows **Add/Remove Programs** dialog to remove versions of the .NET Core runtime and SDK. The following figure shows the **Add/Remove Programs** dialog with several versions of the .NET runtime and SDK installed.
+
+![Add / Remove programs to remove .NET Core](./media/remove-runtime-sdk-versions/programs-and-features.png)
+
+Select any versions you want to remove from your machine and click **Uninstall**.
+
+# [Linux](#tab/Linux)
+
+There are more options to uninstall .NET Core (either SDK or runtime) on Linux. The best way for you to uninstall .NET Core is to mirror the action you used to install .NET Core. The specifics depend on your chosen distribution and the installation method.
+
+> [!IMPORTANT]
+> For Red Hat installations, consult the [Red Hat Getting Started Guide](https://access.redhat.com/documentation/en-us/net_core/2.0/html/getting_started_guide/gs_install_dotnet#install_register_rehel) for information on installing and uninstalling .NET Core.
+
+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 installations will automatically remove the older version upon the successful installation of a newer version.
+
+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.
+- [zypper](https://www.suse.com/documentation/opensuse114/book_opensuse_reference/data/sec_zypper.html) is used on openSUSE.
+- [dnf](https://docs.fedoraproject.org/f27/system-administrators-guide/package-management/DNF.html) is used on Fedora.
+
+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`.
+
+For machines that have installed only the runtime, and not the SDK, the package name is `dotnet-runtime-<version>` for the .NET Core runtime, and `aspnetcore-runtime-<version>` for the entire runtime stack.
+
+.NET Core installations prior to 2.0 did not uninstall the host application when the SDK was uninstalled using the package manager. Using `apt-get`, the command is:
+
+```bash
+apt-get remove dotnet-host
+```
+
+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:
+
+You remove the SDKs and runtimes separately, by removing the directory that contains that version. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands:
+
+```bash
+sudo rm -rf /usr/share/dotnet/sdk/1.0.1
+sudo rm -rf /usr/share/dotnet/shared/Microsoft.NETCore.App/1.0.1
+sudo rm -rf /usr/share/dotnet/shared/Microsoft.AspNetCore.App/1.0.1
+sudo rm -rf /usr/share/dotnet/host/fxr/1.0.1
+```
+
+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.
+
+# [MacOS](#tab/MacOS)
+
+On Mac, you must remove the SDKs and runtimes separately, by removing the directory that contains that version. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands:
+
+```bash
+sudo rm -rf /usr/local/share/dotnet/sdk/1.0.1
+sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.NETCore.App/1.0.1
+sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/1.0.1
+sudo rm -rf /usr/local/share/dotnet/host/fxr/1.0.1
+```
+
+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.

docs/core/versions/selection.md

@@ -9,7 +9,7 @@ ms.date: 06/27/2018
 
 [!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)]
 
-This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end user machines. These policies perform the following:
+This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. These policies perform the following actions:
 
 - Easy and efficient deployment of .NET Core, including security and reliability updates.
 - Use the latest tools and commands independent of target runtime.
@@ -25,11 +25,11 @@ The rest of this document examines those four scenarios.
 
 ## The SDK uses the latest installed version
 
-SDK commands include `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` CLI must choose an SDK version for any command. The .NET Core CLI uses the latest SDK installed on the machine by default. You'll use the .NET Core SDK v2.1.301 when it's installed, even if the project you are working with targets the .NET Core Runtime 2.0. Note that this is true for preview versions as well as released versions. You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.
+SDK commands include `dotnet new`,  , or `dotnet run`. The `dotnet` CLI must choose an SDK version for any command. The .NET Core CLI uses the latest SDK installed on the machine by default. You'll use the .NET Core SDK v2.1.301 when it's installed, even if the project you are working with targets the .NET Core Runtime 2.0. You will use the latest preview versions as well as released versions. You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.
 
 On rare occasions, you may need to use an earlier version of the SDK. You specify that version in a [*global.json* file](../tools/global-json.md). The "use latest" policy means you only use *global.json* to specify a .NET Core SDK version earlier than the latest installed version.
 
-*global.json* can be placed anywhere in the file hierarchy. The CLI searches upward from the project directory for the first *global.json* it finds. You control which projects a given *global.json* applies to by its place in the file system. The .NET CLI searches for a *global.json* file iteratively navigating the path upward from the current working directory. The first *global.json* file found specifies the version used. If that version is installed, that version is used. If the SDK specified in the *global.json* is not found, the .NET CLI rolls forward to the latest SDK installed. This is the same as the default behavior, when no *global.json* file is found.
+*global.json* can be placed anywhere in the file hierarchy. The CLI searches upward from the project directory for the first *global.json* it finds. You control which projects a given *global.json* applies to by its place in the file system. The .NET CLI searches for a *global.json* file iteratively navigating the path upward from the current working directory. The first *global.json* file found specifies the version used. If that version is installed, that version is used. If the SDK specified in the *global.json* is not found, the .NET CLI rolls forward to the latest SDK installed. Roll-forward is the same as the default behavior, when no *global.json* file is found.
 
 The following example shows the *global.json* syntax:
 
@@ -47,7 +47,7 @@ The process for selecting an SDK version is:
 1. `dotnet` uses the SDK specified in the first *global.json* found.
 1. `dotnet` uses the latest installed SDK if no *global.json* is found.
 
-You can learn more about selecting an SDK version in the [Matching rules](../tools/global-json.md#matching-rules) section of the topic on *global.json*.
+You can learn more about selecting an SDK version in the [Matching rules](../tools/global-json.md#matching-rules) section of the article on *global.json*.
 
 ## Target Framework Monikers define build time APIs
 
@@ -103,4 +103,4 @@ Self-contained deployments may require a specific patch version. You can overrid
 <RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion>
 ```
 
-The `RuntimeFrameworkVersion` element  overrides the default version policy. For self-contained deployments, the `RuntimeFrameworkVersion` specifies the *exact* runtime framework version. For framework dependent applications, the `RuntimeFrameworkVersion` specifies the *minimum* required runtime framework version.
+The `RuntimeFrameworkVersion` element  overrides the default version policy. For self-contained deployments, the `RuntimeFrameworkVersion` specifies the *exact* runtime framework version. For framework-dependent applications, the `RuntimeFrameworkVersion` specifies the *minimum* required runtime framework version.