diff --git a/docs/core/tutorials/metapackages.md b/docs/core/tutorials/metapackages.md new file mode 100644 index 0000000000000..3e9f311a8da4f --- /dev/null +++ b/docs/core/tutorials/metapackages.md @@ -0,0 +1,14 @@ + +### 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. + +### 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. diff --git a/docs/core/versions/_trash.md b/docs/core/versions/_trash.md new file mode 100644 index 0000000000000..9df375e96717e --- /dev/null +++ b/docs/core/versions/_trash.md @@ -0,0 +1,55 @@ +## Versioning scheme details + +.NET Core is made of the following parts: + +- A host: either *dotnet.exe* for framework-dependent applications, or *\.exe* for self-contained applications. +- An SDK (the set of tools necessary on a developer's machine, but not in production). +- A runtime. +- A shared framework implementation, distributed as packages. Each package is versioned independently, particularly for patch versioning. +- Optionally, a set of [metapackages](../packages.md) that reference fine-grained packages as a versioned unit. Metapackages can be versioned separately from packages. + +.NET Core also includes a set of target frameworks (for example, `netstandard` or `netcoreapp`) that represent a progressively larger API set, as version numbers are incremented. + +### Packages + +Library packages evolve and version independently. Packages that overlap with .NET Framework System.\* assemblies typically use 4.x versions, aligning with the .NET Framework 4.x versioning (a historical choice). Packages that do not overlap with the .NET Framework libraries (for example, [`System.Reflection.Metadata`](https://www.nuget.org/packages/System.Reflection.Metadata)) typically start at 1.0 and increment from there. + +The packages described by [`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) are treated specially due to being at the base of the platform. + +`NETStandard.Library` packages will typically version as a set, since they have implementation-level dependencies between them. + +### Metapackages + +Versioning for .NET Core metapackages is based on the .NET Core version they are a part of. + +For instance, the metapackages in .NET Core 2.1.3 should all have 2.1 as their `MAJOR` and `MINOR` version numbers. + +The patch version for the metapackage is incremented every time any referenced package is updated. Patch versions don't include an updated framework version. As a result, the metapackages aren't strictly SemVer-compliant because their versioning scheme doesn't represent the degree of change in the underlying packages, but primarily of the API level. + +There are currently two primary metapackages for .NET Core: + +**Microsoft.NETCore.App** + +- v1.0 as of .NET Core 1.0 (these versions match). +- Maps to the `netcoreapp` framework. +- Describes the packages in the .NET Core distribution. + +Note: [`Microsoft.NETCore.Portable.Compatibility`](https://www.nuget.org/packages/Microsoft.NETCore.Portable.Compatibility) is another .NET Core metapackage that exists to enable compatibility with pre-.NET Standard implementation of .NET. It doesn't map to a particular framework, so it versions like a package. + +**NETStandard.Library** + +[`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) describes the libraries that are part of the [.NET Standard](../../standard/library.md). Applies to all .NET implementations that support .NET Standard, such as .NET Framework, .NET Core, and Mono. + +### 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. + +## Versioning in practice + +There are commits and pull requests on .NET Core repos on GitHub on a daily basis, resulting in new builds of many libraries. It isn't practical to create new public versions of .NET Core for every change. Instead, changes are aggregated over an undetermined period of time (for example, weeks or months) before making a new public stable .NET Core version. + +A new version of .NET Core could mean several things: + +- New versions of packages and metapackages. +- New versions of various frameworks, assuming the addition of new APIs. +- New version of the .NET Core distribution. \ No newline at end of file diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index ba1e18755ff81..cb0e9cbae7247 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -7,116 +7,54 @@ 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. -This article aims at clarifying how the .NET Core SDK and runtime are versioned. +This article aims at clarifying version numbers for .NET Core SDK and .NET Core Runtime. [An explanation of version numbers for .NET Standard can be found here](). -There are lots of moving parts that version independently in .NET Core. However, starting with .NET Core 2.0, there is an easy to understand top-level version number that everybody understands to be *the* version of ".NET Core" as a whole. The rest of this document goes into the details of the versioning of all those parts. These details can be important if you're a package manager, for example. - -> [!IMPORTANT] -> The versioning details explained on this topic don't apply to the current version of the .NET Core SDK and runtime. -> The version scheme is changing in future releases. You can see the current proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. +The central problem of versioning is that the .NET Core Runtime and .NET Core SDK add new features at a different rate - in general the .NET Core SDK provides updated tools more quickly than the .NET Core Runtime changes the runtime you use in production. Unfortunately, this problem has resulted in several versioning strategies over the last few years. You can learn about the [history of .NET Core versioning here](). ## Versioning details -With .NET Core 2.0, downloads show a single version number in their file name. The following version numbers were unified: - -* The shared framework and associated runtime. -* The .NET Core SDK and associated .NET Core CLI. -* The `Microsoft.NETCore.App` metapackage. - -The use of a single version number makes it easier for users to know what version of the SDK to install on their dev machines, and what the corresponding version of the shared framework should be when time comes to provision a production environment. When downloading an SDK or runtime, the version number you see is going to be the same. - -### Installers - -With .NET Core 2.0, downloads for the [daily builds](https://github.com/dotnet/core-setup#daily-builds) and [releases](https://www.microsoft.com/net/download/core) adhere to a new naming scheme that is easier to understand. -The installer UI in those downloads was also modified to clearly present the names and versions of the components being installed. In particular, titles now show the same version number that is in the download's file name. +.NET Core 2.1 aligns to the .NET Core Runtime version number. .NET Core Runtime has a major/minor/patch approach to versioning that is roughly aligned with the [semantic versioning]([[Link to semantic versioning later in this doc]]). -#### File name format +The .NET Core SDK will not follow semantic versioning. Since the .NET Core SDK will release faster, we need to communicate both the aligned runtime and the communicate the SDK's own minor and patch releases. To do this, the first two positions of the .NET Core SDK is locked to the .NET Core Runtime it is released with. Each version of the SDK can create applications in this runtime or any lower version. -`[product]-[component]-[major].[minor].[patch]-[previewN]-[optional build #]-[rid].[file ext]` - -Here are some examples of this format: - -``` -dotnet-runtime-2.0.4-macos.10.12-x64.pkg # Mac runtime installer -dotnet-sdk-2.0.4-win10-x64.exe # Windows SDK installer -dotnet-sdk-2.0.4-fedora.24-x64.tar.gz # Fedora 24 binary archive - -#Ubuntu file set needed for the SDK -dotnet-host-2.0.4-ubuntu.16.04-x64.deb # Host / muxer and host policy -dotnet-runtime-2.0.4-ubuntu.16.04-x64.deb # runtime -dotnet-sdk-2.0.4-ubuntu.16.04-x64.deb # SDK tools -``` +The third position of the SDK version number will be used to communicate both the minor and patch number. We will do this by multiplying the minor version by 100 (starting at 100). The final two digits will be the patch number. For example, the release of .NET Core 2.2 are expected to be similar to: -The format is readable and clearly shows what you're downloading, what version it is, and where you can use it. The runtime package name includes `runtime`, and the SDK includes `SDK`. +| Change | .NET Core Runtime | .NET Core SDK (*) | +|-----------------------|-------------------|-------------------| +| Initial release | 2.2.0 | 2.2.100 | +| SDK Patch | 2.2.0 | 2.2.101 | +| Runtime and SDK Patch | 2.2.1 | 2.2.102 | +| SDK Feature change | 2.2.1 | 2.2.200 | -#### UI string format +(*) this chart uses .NET Core Runtime as the example because a historic artifact meant the first SDK for .NET Core 2.1 is 2.1.300. See the [history of .NET Core versioning here]() -All web site descriptions and UI strings in the installers are kept consistent, accurate, and simple. The following table shows some examples: +NOTES: -| Installer | Window Title | Other content in installer | What is installed | -| :-- | :-- | :-- | :-- | -| 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 | +* If the SDK has ten feature updates before a runtime feature update we will roll into the 1000 series with numbers like 2.2.1000 as the feature release following 2.2.900. This is not expected to occur. +* 99 patch releases without a feature release will not occur. If we approach this number, we will force a feature release. -Preview releases differ only slightly: +You can see more details in the initial proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. -| Installer | Window Title | Other content in installer | What is installed | -| :-- | :-- | :-- | :-- | -| 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 | +## Product naming -It may happen that an SDK release contains more than one version of the runtime. When that happens, the installer UX looks like the following (only the SDK version is shown and the installed Runtime versions are shown on a summary page at the end of the installation process on Windows and Mac): +Web site descriptions and UI strings in the installers use the .NET Core Runtime major and minor version numbers. The following table shows some examples: -| Installer | Window Title | Other content in installer | What is installed | -| :-- | :-- | :-- | :-- | -| SDK | .NET Core 2.1 SDK (x64) Installer | .NET Core 2.1.1 SDK
.NET Core 2.1.1 Runtime
.NET Core 2.0.6 Runtime | .NET Core 2.1.1 Tools + .NET Core 2.1.1 Runtime + .NET Core 2.0.6 Runtime | +| Installer | Description | +|-----------------|----------------------------------------| +| SDK | .NET Core 2.1 SDK (v2.1.300) | +| Runtime | .NET Core 2.0 Runtime | +| SDK Preview | .NET Core 2.1 SDK (v2.1.300) Preview 1 | +| Runtime Preview | .NET Core 2.1 Runtime Preview 1 | -It's also possible that .NET Core Tools need to be updated, without runtime changes. In that case, the SDK version is increased (for example, to 2.1.2) and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the next time as 2.1.3). - -### Package managers +## Package managers .NET Core can be distributed by other entities than Microsoft. In particular, Linux distribution owners and package maintainers may add .NET Core packages to their package managers. For recommendations on how those packages should be named and versioned, see [.NET Core distribution packaging](../build/distribution-packaging.md). -#### Minimum package set - -* `dotnet-runtime-[major].[minor]`: a runtime with the specified version (only the latest patch version for a given major+minor combination should be available in the package manager). New patch versions update the package, but new minor or major versions are separate packages. - - **Dependencies**: `dotnet-host` - -* `dotnet-sdk`: the latest SDK. `update` rolls forward major, minor, and patch versions. - - **Dependencies**: the latest `dotnet-sdk-[major].[minor]`. - -* `dotnet-sdk-[major].[minor]`: the SDK with the specified version. The version specified is the highest included version of included shared frameworks, so that users can easily relate an SDK to a shared framework. New patch versions update the package, but new minor or major versions are separate packages. - - **Dependencies**: `dotnet-host`, one or more `dotnet-runtime-[major].[minor]` (one of those is used by the SDK code itself, the others are here for users to build and run against). - -* `dotnet-host`: the latest host. - -##### Preview versions - -Package maintainers may decide to include preview versions of the runtime and SDK. Don't include those preview versions in the unversioned `dotnet-sdk` package, but you can release them as versioned packages with an additional preview marker appended to the major and minor version sections of the name. For example, there may be a `dotnet-sdk-2.0-preview1-final` package. - -### 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-runtime -* 1.0.8-sdk -* 2.0.4-runtime -* 2.0.4-sdk -* 2.1.1-runtime -* 2.1.1-sdk - -The SDK tags should be updated to represent the SDK version rather than Runtime. - -It's also possible that the .NET Core CLI tools (included in the SDK) are fixed but reship with an existing runtime. In that case, the SDK version is increased (for example, to 2.1.2), and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the following time as 2.1.3). - ## Semantic Versioning -.NET Core uses [Semantic Versioning (SemVer)](http://semver.org/), adopting the use of `MAJOR.MINOR.PATCH` versioning, using the various parts of the version number to describe the degree and type of change. +.NET Core *Runtime* roughly adheres to [Semantic Versioning (SemVer)](http://semver.org/), adopting the use of `MAJOR.MINOR.PATCH` versioning, using the various parts of the version number to describe the degree and type of change. ``` MAJOR.MINOR.PATCH[-PRERELEASE-BUILDNUMBER] @@ -124,13 +62,14 @@ MAJOR.MINOR.PATCH[-PRERELEASE-BUILDNUMBER] The optional `PRERELEASE` and `BUILDNUMBER` parts are never part of supported releases and only exist on nightly builds, local builds from source targets, and unsupported preview releases. -### How version numbers are incremented? +### Guidelines for incrementing runtime version numbers `MAJOR` is incremented when: +- Significant changes occur to the product, or a new product direction. +- Breaking changes need to be taken. The bar for breaking changes will be high. - An old version is no longer supported. - A newer `MAJOR` version of an existing dependency is adopted. -- The default setting of a compatibility quirk is changed to "off." `MINOR` is incremented when: @@ -148,6 +87,10 @@ The optional `PRERELEASE` and `BUILDNUMBER` parts are never part of supported re When there are multiple changes, the highest element affected by individual changes is incremented, and the following ones are reset to zero. For example, when `MAJOR` is incremented, `MINOR` and `PATCH` are reset to zero. When `MINOR` is incremented, `PATCH` is reset to zero while `MAJOR` is left untouched. +## Version numbers in file names + +When you download .NET Core, the name of the downloaded file carries the version, for example, `dotnet-sdk-2.1.300-win10-x64.exe`. + ### Preview versions Preview versions have a `-preview[number]-([build]|"final")` appended to the version. For example, `2.0.0-preview1-final`. @@ -156,97 +99,6 @@ Preview versions have a `-preview[number]-([build]|"final")` appended to the ver After a release goes out, the release branches generally stop producing daily builds and instead start producing servicing builds. Servicing versions have a `-servicing-[number]` appended to the version. For example, `2.0.1-servicing-006924`. -### LTS vs. current - -There are two trains of releases for .NET Core: Long Term Support (LTS) and Current. That enables users to pick the level of stability and new features they want, while still being supported. - -- LTS means you get new features less frequently, but you have a more mature platform. LTS also has a longer period of support. -- Current means you get new features and APIs more frequently, but the disadvantage is that you have a shorter window of time to install updates, and those updates happen more frequently. Current is also fully supported but the support period is shorter than LTS. - -A "Current" version may get promoted to LTS. - -"LTS" and "Current" should be considered as labels that we put on specific releases to make a statement about the associated level of support. - -For more information, see [.NET Core Support Lifecycle Fact Sheet](https://www.microsoft.com/net/core/support). - -## Versioning scheme details - -.NET Core is made of the following parts: - -- A host: either *dotnet.exe* for framework-dependent applications, or *\.exe* for self-contained applications. -- An SDK (the set of tools necessary on a developer's machine, but not in production). -- A runtime. -- A shared framework implementation, distributed as packages. Each package is versioned independently, particularly for patch versioning. -- Optionally, a set of [metapackages](../packages.md) that reference fine-grained packages as a versioned unit. Metapackages can be versioned separately from packages. - -.NET Core also includes a set of target frameworks (for example, `netstandard` or `netcoreapp`) that represent a progressively larger API set, as version numbers are incremented. - -### .NET Standard - -.NET Standard has been using a `MAJOR.MINOR` versioning scheme. `PATCH` level isn't useful for .NET Standard because it expresses a set of contracts that are iterated on less often and doesn't present the same requirements for versioning as an actual implementation. - -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 there is no guarantee that future versions of .NET Core will map to the same .NET Standard version. .NET Core can ship APIs that aren't defined by .NET Standard, and, as such, may ship new versions without requiring a new .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. - -### Packages - -Library packages evolve and version independently. Packages that overlap with .NET Framework System.\* assemblies typically use 4.x versions, aligning with the .NET Framework 4.x versioning (a historical choice). Packages that do not overlap with the .NET Framework libraries (for example, [`System.Reflection.Metadata`](https://www.nuget.org/packages/System.Reflection.Metadata)) typically start at 1.0 and increment from there. - -The packages described by [`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) are treated specially due to being at the base of the platform. - -`NETStandard.Library` packages will typically version as a set, since they have implementation-level dependencies between them. - -### Metapackages - -Versioning for .NET Core metapackages is based on the .NET Core version they are a part of. - -For instance, the metapackages in .NET Core 2.1.3 should all have 2.1 as their `MAJOR` and `MINOR` version numbers. - -The patch version for the metapackage is incremented every time any referenced package is updated. Patch versions don't include an updated framework version. As a result, the metapackages aren't strictly SemVer-compliant because their versioning scheme doesn't represent the degree of change in the underlying packages, but primarily of the API level. - -There are currently two primary metapackages for .NET Core: - -**Microsoft.NETCore.App** - -- v1.0 as of .NET Core 1.0 (these versions match). -- Maps to the `netcoreapp` framework. -- Describes the packages in the .NET Core distribution. - -Note: [`Microsoft.NETCore.Portable.Compatibility`](https://www.nuget.org/packages/Microsoft.NETCore.Portable.Compatibility) is another .NET Core metapackage that exists to enable compatibility with pre-.NET Standard implementation of .NET. It doesn't map to a particular framework, so it versions like a package. - -**NETStandard.Library** - -[`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) describes the libraries that are part of the [.NET Standard](../../standard/library.md). Applies to all .NET implementations that support .NET Standard, such as .NET Framework, .NET Core, and Mono. - -### 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. - -## Versioning in practice - -When you download .NET Core, the name of the downloaded file carries the version, for example, `dotnet-sdk-2.0.4-win10-x64.exe`. - -There are commits and pull requests on .NET Core repos on GitHub on a daily basis, resulting in new builds of many libraries. It isn't practical to create new public versions of .NET Core for every change. Instead, changes are aggregated over an undetermined period of time (for example, weeks or months) before making a new public stable .NET Core version. - -A new version of .NET Core could mean several things: - -- New versions of packages and metapackages. -- New versions of various frameworks, assuming the addition of new APIs. -- New version of the .NET Core distribution. - -### 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. - -### 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. - ## See also [Target frameworks](../../standard/frameworks.md) diff --git a/docs/core/versions/lts-current.md b/docs/core/versions/lts-current.md index d6a8955512b70..c38e5fedd0005 100644 --- a/docs/core/versions/lts-current.md +++ b/docs/core/versions/lts-current.md @@ -11,7 +11,22 @@ This is a general description of .NET Core support. ## LTS and Current Release Trains -Having two support release trains is a common concept in use throughout the software world, specially for open-source projects like .NET Core. .NET Core has the following support release trains: [Long Term Support (LTS)](https://en.wikipedia.org/wiki/Long-term_support) and Current. LTS releases are maintained for stability over their lifecycle, receiving fixes for important issues and security fixes. New feature work and additional bug fixes take place in Current releases. From a support perspective, these release trains have the following support lifecycle attributes. +There are two trains of releases for .NET Core: Long Term Support (LTS) and Current. That enables users to pick the level of stability and new features they want, while still being supported. + +Having two support release trains is a common concept in use throughout the software world, specially for open-source projects like .NET Core. .NET Core has the following support release trains: [Long Term Support (LTS)](https://en.wikipedia.org/wiki/Long-term_support) and Current. LTS releases are maintained for stability over their lifecycle, receiving fixes for important issues and security fixes. New feature work and additional bug fixes take place in Current releases. + +- LTS means you get new features less frequently, but you have a more mature platform. LTS also has a longer period of support. +- Current means you get new features and APIs more frequently, but the disadvantage is that you have a shorter window of time to install updates, and those updates happen more frequently. Current is also fully supported but the support period is shorter than LTS. + +A "Current" version may get promoted to LTS. + +"LTS" and "Current" should be considered as labels that we put on specific releases to make a statement about the associated level of support. + +For more information, see [.NET Core Support Lifecycle Fact Sheet](https://www.microsoft.com/net/core/support). + +## Support timeframes + +From a support perspective, these release trains have the following support lifecycle attributes. LTS releases are * Supported for three years after the general availability date of a LTS release diff --git a/docs/core/versions/version-history.md b/docs/core/versions/version-history.md new file mode 100644 index 0000000000000..f38a88fb5ebfd --- /dev/null +++ b/docs/core/versions/version-history.md @@ -0,0 +1,47 @@ +--- +Your magic stuff +--- + +# NET Core version history + +Version numbers for the .NET Core are challenging because .NET Core SDK and .NET Core Runtime release on different cadences. Because of this, we can do only two of the following three things: + +1. Release independently, specifically allowing tools, C# and VB to advance faster than the .NET Core Runtime. +2. Maintain alignment in version numbers between .NET Core SDK and .NET Core Runtime. +3. Use semantic versioning for both the .NET Core SDK and .NET Core Runtime. + +2.0.0 forced version alignment and this proceeded smoothly for one release. In December 2017 .NET Core SDK had a feature release, with no corresponding release in the .NET Core Runtime. The team chose goals 1 and 3, losing alignment between the .NET Core Runtime and SDK and resulted in a several .NET Core SDK 2.1.x versions that were released before .NET Core Runtime 2.1. Since the SDK is not forwards compatible, these 2.1.x SDK versions could not target .NET Core Runtime 2.1. The team responded to the considerable confusion this caused by switching to goals 1 and 2, abandoning semantic versioning as described in [.NET Core versioning]([[ index.md]]). + +Because the timing of the decision to abandon semantic versioning was made between , there were transitional releases in the 2.1.10x and 2.1.20x version number ranges that can also not target .NET Core Runtime 2.1. + +The first two digits of the version numbers realign with the 2.1.0 version of the .NET Core Runtime and the 2.1.300 version of the .NET Core SDK. + +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 | +|------------|------------------|--------------------|-------------|-------------|-------| +| 2017-03-07 | 1.0.1 | 1.0.4,1.1.1 | 7.0 | 15.0 | | +| 2017-05-09 | 1.0.4 | 1.0.5, 1.1.2 | | | | +| 2017-09-21 | 1.1.4 | 1.0.7, 1.1.4 | | | | +| 2017-11-14 | 1.1.7 | 1.0.8, 1.1.5 | | | | +| 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 | | | +| 2017-11-14 | 2.0.3 | 2.0.3 | 7.1 | 15.1 | | +| 2017-12-04 | 2.1.2 | 2.0.3 | 7.1 | 15.1 | (1) | +| 2018-01-09 | 2.1.4 | 2.0.5 | 7.1 | 15.1 | (1) | +| 2018-03-13 | 2.1.100 | 2.0.5 | 7.2 | 15.2 | (1,2) | +| 2018-03-13 | 2.1.101 | 2.0.6 | 7.2 | 15.2 | (1,2) | +| 2018-03-19 | 2.1.102 | 2.0.6 | 7.2 | 15.2 | (1,2) | +| 2018-03-22 | 2.1.103 | 2.0.6 | 7.2 | 15.2 | (1,2) | +| 2018-04-04 | 2.1.104 | 2.0.6 | 7.2 | 15.2 | (1,2) | +| 2018-04-27 | 2.1.105 | 2.0.7 | 7.2 | 15.2 | (1,2) | +| 2018-05-08 | 2.1.200 | 2.0.8 | 7.2 | 15.2 | (1,2) | +| 2018-05-21 | 2.1.201 | 2.0.8 | 7.2 | 15.2 | (1,2) | +| 2018-05-30 | 2.1.300 | 2.1.0 | 7.3 | 15.3 | (3) | + +(1) These versions of .NET Core SDK 2.1.x cannot build apps targeting .NET Core Runtime 2.1.x +(2) The new version number scheme was decided at the start of 2018. However, there were two feature level releases before .NET Core Runtime 2.10 released. Thus, 2.1.10x and 2.20x represent a transition period. +(3) The .NET Core 2.1 release represents unification of version numbers on the new scheme +(4) A nightly build of the .NET Core SDK appeared with the version number starting with 15. This must be manually removed from the machine. \ No newline at end of file diff --git a/docs/core/versions/versioning-docker.md b/docs/core/versions/versioning-docker.md new file mode 100644 index 0000000000000..4d38f75d11f63 --- /dev/null +++ b/docs/core/versions/versioning-docker.md @@ -0,0 +1,15 @@ + +### 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-runtime +* 1.0.8-sdk +* 2.0.4-runtime +* 2.0.4-sdk +* 2.1.1-runtime +* 2.1.1-sdk + +The SDK tags should be updated to represent the SDK version rather than Runtime. + +It's also possible that the .NET Core CLI tools (included in the SDK) are fixed but reship with an existing runtime. In that case, the SDK version is increased (for example, to 2.1.2), and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the following time as 2.1.3). \ No newline at end of file diff --git a/docs/core/versions/versioning-for-packages.md b/docs/core/versions/versioning-for-packages.md new file mode 100644 index 0000000000000..e70574939f1ad --- /dev/null +++ b/docs/core/versions/versioning-for-packages.md @@ -0,0 +1,19 @@ +#### Minimum package set + +* `dotnet-runtime-[major].[minor]`: a runtime with the specified version (only the latest patch version for a given major+minor combination should be available in the package manager). New patch versions update the package, but new minor or major versions are separate packages. + + **Dependencies**: `dotnet-host` + +* `dotnet-sdk`: the latest SDK. `update` rolls forward major, minor, and patch versions. + + **Dependencies**: the latest `dotnet-sdk-[major].[minor]`. + +* `dotnet-sdk-[major].[minor]`: the SDK with the specified version. The version specified is the highest included version of included shared frameworks, so that users can easily relate an SDK to a shared framework. New patch versions update the package, but new minor or major versions are separate packages. + + **Dependencies**: `dotnet-host`, one or more `dotnet-runtime-[major].[minor]` (one of those is used by the SDK code itself, the others are here for users to build and run against). + +* `dotnet-host`: the latest host. + +##### Preview versions + +Package maintainers may decide to include preview versions of the runtime and SDK. Don't include those preview versions in the unversioned `dotnet-sdk` package, but you can release them as versioned packages with an additional preview marker appended to the major and minor version sections of the name. For example, there may be a `dotnet-sdk-2.0-preview1-final` package. diff --git a/docs/core/versions/versioning-standard.md b/docs/core/versions/versioning-standard.md new file mode 100644 index 0000000000000..011b22d873e0b --- /dev/null +++ b/docs/core/versions/versioning-standard.md @@ -0,0 +1,21 @@ +--- +Your magic stuff +--- + +# 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. + +The .NET Standard reference implementation uses a `MAJOR.MINOR` versioning scheme. `PATCH` level isn't useful for .NET Standard because if exposes only an API (no implementation) and by definition any change to the API would represent a change in the feature set, and thus a minor version bump. + +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. + +| .NET Core | .NET Standard | +|-----------|---------------| +| 1.0 | up to 1.6 | +| 2.0 | up to 2.0 | +| 2.1 | up to 2.1 | + +## See also