diff --git a/Documentation/specs/cli-installation-scenarios.md b/Documentation/specs/cli-installation-scenarios.md index 49be32fd6..16182c234 100644 --- a/Documentation/specs/cli-installation-scenarios.md +++ b/Documentation/specs/cli-installation-scenarios.md @@ -17,8 +17,6 @@ Obtaining .NET CLI * [Acquisition modes](#acquisition-modes) * [Native installers](#native-installers) * [Installation script](#installation-script) - * [Windows one-liner](#windows-command) - * [OSX/Linux one-liner](#osxlinux-shell-command) * [Complete manual installation](#complete-manual-installation) * [Docker](#docker) * [NuGet Packages](#nuget-packages) @@ -113,28 +111,17 @@ A list of dependencies can be found on [dependency list](TBD). ## Channels Channels represent a way for users who are getting the CLI to reason about the stability and quality of the bits they are getting. This is one more way for the user to be fully aware of the state the bits that are being installed are in and to set proper expectations on first use. -The table below outlines the channels: - -| Property | Description | +| Channel | Description | |------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Future | Unstable bits that are "bleeding edge". Users are not expected to use this channel often, however it is there for those situations when someone needs/wants a feature that hasn't been stabilizied yet. Also, used for internal testing. | -| Preview | Pre-release stable builds with known issues and/or known feature gaps. We are OK with users installing these for preview purposes. | -| Production | Actual releases. Most users are encouraged to install these. | - -Below table shows the mapping between the channels, branches and feeds for the Debian pacakage. Since channels also impact the NuGet packages, it also contains the version of the package used and the feed to opt in to each channel. - -| Channel | Branch | Debian feed | Debian package name | NuGet version | NuGet feed | -|------------ |----------- |------------- |--------------------- |--------------- |--------------------------------------- | -| Future | master | Development | dotnet-future | 1.0.0-dev-* | https://dotnet.myget.org/f/dotnet-cli | -| Preview | rel/ | Development | dotnet-sdk- | 1.0.0-beta-* | https://dotnet.myget.org/f/dotnet-cli | -| Production | rel/ | Production | dotnet-sdk- | 1.0.0 | https://api.nuget.org/v3/index.json | +| LTS | Latest long-term supported release. | +| Current | Most current release - typically 'preview' releases. | ## Funnels and discovery mechanisms for CLI bits There are multiple ways that we will funnel users towards the installers for the CLI: 1. [Getting Started Page](https://aka.ms/dotnetcoregs) -2. [Repo landing page](https://github.com/dotnet/cli/blob/rel/1.0.0/README.md) +2. [Repo landing page](../../README.md) 3. Package repositories for platforms (`apt-get`, `brew` etc.) 4. IDEs and editors that integrate with CLI (e.g. Visual Studio, VS Code, Sublime etc.) @@ -152,11 +139,10 @@ The below table shows other pertinent information for installs on the "Getting s | Debian feed | Development | | Brew repo/tap | Brew binary repo (https://github.com/Homebrew/homebrew-binary) | | CentOS feed | TBD | -| Local install scripts | Latest from rel/1.0.0 | ### Repo landing page -The repo landing page can be found on: https://github.com/dotnet/cli/blob/rel/1.0.0/README.md. Download links on the landing page should be decreased in importance. First thing for "you want to get started" section should link to the getting started page on the marketing site. The Repo Landing Page should be used primarily by contributors to the CLI. There should be a separate page that has instructions on how to install both the latest stable as well as latest development with proper warnings around it. The separate page is to really avoid the situation from people accidentally installing unstable bits (since search engines can drop them in the repo first). +The repo landing page can be found on: [Repo landing page](../../README.md). Download links on the landing page should be decreased in importance. First thing for "you want to get started" section should link to the getting started page on the marketing site. The Repo Landing Page should be used primarily by contributors to the CLI. There should be a separate page that has instructions on how to install both the latest stable as well as latest development with proper warnings around it. The separate page is to really avoid the situation from people accidentally installing unstable bits (since search engines can drop them in the repo first). The source branches and other items are actually branch specific for the repo landing page. As the user switches branches, the links and badges on the page will change to reflect the builds from that branch. @@ -197,13 +183,12 @@ This install covers the following main scenario: The features the script needs to support/have are: -* Support for dev and stable channel +* Support for specifying the channel * Support for specifying the version -* Support for specfying the installation location -* Support specifying whether the debug package needs to be downloaded +* Support for specifying the installation location * Automatically add the install to $PATH unless --no-path/-NoPath is present -The installation script exists in this repo under `scripts/obtain` path. However, for most users it is reccomended to use the stable version that is hosted on [.NET Core main website](https://dot.net). The direct path to the scripts are: +It is recommended to use the stable version that is hosted on [.NET Core main website](https://dot.net). The direct path to the scripts are: * https://dot.net/v1/dotnet-install.sh (bash, UNIX) * https://dot.net/v1/dotnet-install.ps1 (powershell, Windows) @@ -214,10 +199,9 @@ The following arguments are needed for the installation script: | dotnet-install.sh arg (Linux, OSX) | dotnet-install.ps1 arg (Windows) | Defaults | Description | |------------------------------------|----------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| --channel | -Channel | "production" | Which channel (i.e. "Future", "preview", "production", "release/1.1.0") to install from. | -| --version | -Version | Latest | Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to Latest for that channel. | +| --channel | -Channel | "LTS" | Which channel (i.e. "LTS", "Current", "1.0", "2.0", etc) to install from. | +| --version | -Version | Latest | Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). The 'version' parameter supersedes the 'channel' parameter. | | --install-dir | -InstallDir | .dotnet | Path to where to install the CLI bundle. The directory is created if it doesn't exist. On Linux/OSX this directory is created in the user home directory (`$HOME`). On Windows, this directory is created in `%LocalAppData%`. | -| --debug-symbols | -DebugSymbols | false | Whether to use the "fat" packages that contain debugging symbols or not. | | --no-path | -NoPath | false | Do not export the installdir to the path for the current session. This makes CLI tools available immediately after install. | | --shared-runtime | -SharedRuntime | false | Install just the shared runtime bits, not the entire SDK. | | --architecture | -Architecture | Current OS (``) | Architecture to install. The possible values are ``, `x64` and `x86`. | @@ -231,62 +215,59 @@ The following arguments are needed for the installation script: Windows: ``` -./dotnet-install.ps1 -Channel 'release/1.1.0' -SharedRuntime -Version 1.1.1 +./dotnet-install.ps1 -SharedRuntime -Version 1.1.0 ``` macOS/Linux: ``` -./dotnet-install.sh --channel 'release/1.1.0' --shared-runtime --version 1.1.1 +./dotnet-install.sh --shared-runtime --version 1.1.0 ``` -##### Install the latest Future CLI +##### Install the latest supported CLI Windows: ``` -./dotnet-install.ps1 -Channel Future +./dotnet-install.ps1 -Channel LTS ``` OSX/Linux: ``` -./dotnet-install.sh --channel Future +./dotnet-install.sh --channel LTS ``` -##### Install the latest preview to specified location +##### Install the latest CLI to specified location Windows: ``` -./dotnet-install.ps1 -Channel preview -InstallDir C:\cli +./dotnet-install.ps1 -Channel Current -InstallDir C:\cli ``` OSX/Linux: ``` -./dotnet-install.sh --channel preview --install-dir ~/cli +./dotnet-install.sh --channel Current --install-dir ~/cli ``` -#### Windows obtain one-liner example +##### Install the latest CLI in the 2.0 channel +Windows: ``` -@powershell -NoProfile -ExecutionPolicy unrestricted -Command "&{iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/dotnet-install.ps1'))}" +./dotnet-install.ps1 -Channel 2.0 ``` - -#### OSX/Linux obtain one-liner - +OSX/Linux: ``` -curl -sSL https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/dotnet-install.sh | bash /dev/stdin +./dotnet-install.sh --channel 2.0 ``` ### Docker [Docker](https://docs.docker.com/) has become a pretty good way to use developer tools, from trying them out in an interactive image use to using it for deployment. We have Docker images on DockerHub already. -Docker images should always be updated as we make new releases. We should have Docker images of stable releases, built from the rel/* branches. +Docker images should always be updated as we make new releases. We should have Docker images of stable releases, built from the release branches. ### NuGet packages -NuGet packages of the CLI bits that make sense are published to relevant feeds. The developer who wishes to use these needs to specify a version. The version is used to opt-in to the three channels above. The actuall "installation" here is restoring the package as a dependency for a certain project (i.e. `ProjectServer` or similar). - -The table in the [channels section](#channels) has the examples of mapping between branches and NuGet package versions. +NuGet packages of the CLI bits that make sense are published to relevant feeds. The developer who wishes to use these needs to specify a version. The actual "installation" here is restoring the package as a dependency for a certain project (i.e. `ProjectServer` or similar). ## Acquiring through other products ### IDEs and editors -Anything that goes into the higher-level tools should always use a stable build of CLI coming frol rel/* branches as required. +Anything that goes into the higher-level tools should always use a stable build of CLI coming frol release branches as required. If there exist any mechanism that notifies users of updates of the CLI, it should ideally point users to the Getting Started page to acquire the installers, or, if that is deemed too heavy-handed, it should point people to the last stable release. If there is a need of the URL to be "baked in" to the higher-level tool, that URL should be an aka.ms URL because it needs to be stable on that end. diff --git a/Documentation/specs/installation-scenarios.md b/Documentation/specs/installation-scenarios.md deleted file mode 100644 index 67f86472d..000000000 --- a/Documentation/specs/installation-scenarios.md +++ /dev/null @@ -1,248 +0,0 @@ -# Notes -This section describes placeholders used inside this spec. - -| Placeholder | Description | -| ---: | :--- | -| `` | `(future|preview|production)`. [See more info](#channels) | -| `` | version string | -| `` | `(win|ubuntu|rhel|osx|debian)` - code for OS name | -| `` | Lowest supported OS Version | -| `` | Processor architecture related to binaries produced | -| `` | File extension. This will be described in more details later for each OS separately. | -| `` | Abbreviation for: `.`. [See more info](#osid) | -| `` | `(latest|lkg)` | -| `` | Executable extension including dot specific to OS (can be empty string) | -| `` | Commit hash related to state of repository from where build with specific `` was build | -| `` | Name of the debian package. [See more info](#debian-feed-relation) | - -# Build Output -Each official, successful build should create and upload packages to location described by following URLs: -``` -https://dotnetcli.azureedge.net/dotnet///dotnet... - -Currently: -https://dotnetcli.azureedge.net/dotnet//Binaries//dotnet-sharedframework--..zip -https://dotnetcli.azureedge.net/dotnet//Binaries//dotnet-host--..zip -https://dotnetcli.azureedge.net/dotnet//Binaries//dotnet--..zip -``` -Content of the package should contain binaries which layout will be described later. - -Additionally each build should update `latest` [version descriptors](#version-descriptors) - -## Windows output - -Nuget - WIP, this should include versioning scheme - -| `` | Description | -| --- | :--- | -| exe | Installer bundle. It should be used by end customers | -| zip | Packed binaries. Used by [installation script](#installation-scripts) | -| symbols.zip | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | - -### Including dotnet cli installer as part of your bundle - -In order to install dotnet cli with other installer you need an MSI package. To get MSI, download exe bundle and extract it using `dark` tool which is part of [WiX Toolset](http://wixtoolset.org): -``` -dark.exe -x -``` - -## OSX output - -| `` | Description | -| --- | :--- | -| pkg | WIP | -| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | -| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | - -## Ubuntu output - -| `` | Description | -| --- | :--- | -| deb | Debian package. This package is being pushed to a [debian feed](#debian-feed) | -| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | -| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | - -## RedHat/CentOS output - -| `` | Description | -| --- | :--- | -| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | -| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | - -## Debian output - -| `` | Description | -| --- | :--- | -| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | -| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | - -## Example build output links -WIP - -## Questions -- Should include channel name to avoid situation where you have two files on your computer and latest file might have lower version than the newest? - -# Obtaining dotnet - -## Installation scripts - -Installation script is a shell script which lets customers install dotnet. - -For Windows we are using PowerShell script (install-dotnet.ps1). -For any other OS we are using bash script (install-dotnet.sh) - -WIP: Exact script action description. - -### Script arguments description - -| PowerShell/Bash script | Bash script only | Default | Description | -| --- | --- | --- | --- | -| -Channel | --channel | production | Which [channel](#channels) to install from. Possible values: `future`, `preview`, `production` | -| -Version | --version | `global.json` or `latest` | `global.json` currently not supported | -| -InstallDir | --prefix | Windows: `%LocalAppData%\Microsoft\.dotnet` | Path to where install dotnet. Note that binaries will be placed directly in a given directory. | -| -Architecture | ~~--architecture~~ | auto | Possible values: `auto`, `x64`, `x86`. `auto` refers to currently running OS architecture. This switch is currently not supported in bash scripts. | -| -DebugSymbols | --debug-symbols | `` | If switch present, installation will include debug symbol | -| -DryRun | --dry-run | `` | If switch present, installation will not be performed and instead deterministic invocation with specific version and zip location will be displayed. | -| -NoPath | --no-path | `` | If switch present the script will not set PATH environmental variable for the current process. | -| -Verbose | --verbose | `` | If switch present displays diagnostics information. | -| -AzureFeed | --azure-feed | See description | Azure feed URL, default: `https://dotnetcli.azureedge.net/dotnet` | - -### Script location -WIP: permanent link for obtaining latest version -WIP: versioning description -Newest version of the scripts can be found in the repository under following directory: -``` -https://github.com/dotnet/cli/tree/rel/1.0.0/scripts/obtain -``` - -Older version of the script can be obtained using: -``` -https://github.com/dotnet/cli/blob//scripts/obtain -``` - -## Getting started page -WIP - -## Repo landing page -WIP - -# Version descriptors -## Version pointers -Version pointers represent URLs to the latest and Last Known Good (LKG) builds. -Specific URLs TBD. This will be something similar to following: -``` -/dotnet//..version -``` - -`` TBD - -## Version files -Version files can be found in multiple places: -- Package: relative path inside the package ./.version -- Latest/LKG version file: WIP - -URL: -``` -https://dotnetcli.azureedge.net/dotnet//..version -``` - -### File content -Each version file contains two lines describing the build: -``` - - -``` - -## Version badge -Version badge (SVG) is an image with textual representation of ``. It can be found under following URL: -``` -https://dotnetcli.azureedge.net/dotnet//..svg -``` - -## Questions/gaps -- Version Pointer links should be permanent and hosted on a separate domain - -# Package content -Currently package is required to contain two files: -- .version - [version file](#version-file) -- dotnet - entry point for all dotnet commands - -## Disk Layout -``` -.\ - .version - bin\ - dotnet -``` - -# Channels -Currently we have 3 channels which gives us idea about stability and quality of our product. - -| Channel name | Description | -| :---: | :--- | -| future | This channel can contain new features which may not be fully complete. This is usually most unstable channel. | -| preview | This channel is in the process of stablization. Most of the bugs and gaps are known. No new features expected. | -| production | This is the most stable channel. Features and gaps are known. No breaking changes can be expected. This channel will only be producing new versions on hotfixes. | - -## Github branches relation - -Each branch on each successful build produces packages described in [build output](#build-output). Mapping between branches and channel name can be found in the table below: - -| Channel name | Github branch | -| :---: | :--- | -| future | master | -| preview | rel/1.0.0 | -| production | N/A, prod? | - -## Debian feed relation - -After each successful build package is being pushed to the debian feed. More information on debian feed can be found [here](#debian-feed). - -| Channel name | `` | -| :---: | :--- | -| future | dotnet-future | -| preview | dotnet-preview | -| production | dotnet | - -## Nuget semantic version suffix relation -WIP - -## Questions -- What is the bar for triggering hotfix? - -# OSID - -OSID represents abbreviation for: -``` -. -``` -This naming scheme gives us flexibility to easily create new binaries when OS makes a breaking change without creating confusing names. - -In example, we currently put `api-ms-*.dll` files in our binaries. Those files are not needed on Windows 8 and higher. When using name `win7.x64` we can easily decide to get rid of `api-ms-*.dll` in the newest packages and simply call new version `win8.x64` which would mean that from Windows 8 forward those are recommended binaries (there is currently no issue with those files and this should be only treated as an example). - -# Debian feed - -Newest binaries in debian feed may be delayed due to external issues by up to 24h. - -## Obtaining binaries - -Add debian feed: -``` -sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list' - -sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893 - -sudo apt-get update -``` - -Install: -``` -sudo apt-get install = -``` - -## Questions -- Is debian version compatible with `` or does it require additional revision number, i.e.: `1.0.0.001598-1`? -- How to differentiate between Debian package for Debian and Debian package for Ubuntu? -- -# Symbol packages -WIP