Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update for version selection articles #25039

Merged
merged 5 commits into from
Jul 9, 2021
Merged

Update for version selection articles #25039

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
794f2a6
Update for version info
adegeo Jul 8, 2021
37ba639
standardize on application for article
adegeo Jul 8, 2021
161f566
Apply suggestions from code review
adegeo Jul 8, 2021
998d2a4
feedback
adegeo Jul 8, 2021
faa4290
Update docs/core/versions/selection.md
adegeo Jul 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion docs/core/project-sdk/msbuild-props.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,8 @@ The following MSBuild properties are documented in this section:
- [IsPublishable](#ispublishable)
- [PreserveCompilationContext](#preservecompilationcontext)
- [PreserveCompilationReferences](#preservecompilationreferences)
- [RollForward](#rollforward)
- [RuntimeFrameworkVersion](#runtimeframeworkversion)
- [RuntimeIdentifier](#runtimeidentifier)
- [RuntimeIdentifiers](#runtimeidentifiers)
- [UseAppHost](#useapphost)
Expand Down Expand Up @@ -330,6 +332,34 @@ The `PreserveCompilationReferences` property is similar to the [PreserveCompilat

For more information, see [Razor SDK properties](/aspnet/core/razor-pages/sdk#properties).

### RollForward

The `RollForward` property controls how the application chooses a runtime when multiple runtime versions are available. This value is output to the *.runtimeconfig.json* as the `rollForward` setting.

```xml
<PropertyGroup>
<RollForward>LatestMinor</RollForward>
</PropertyGroup>
```

Set `RollForward` to one of the following values:

[!INCLUDE [roll-forward-table](../../../includes/roll-forward-table.md)]

For more information, see [Control roll-forward behavior](../versions/selection.md#control-roll-forward-behavior).

### RuntimeFrameworkVersion

The `RuntimeFrameworkVersion` property specifies the version of the runtime to use when publishing. Specify a runtime version:

``` xml
<PropertyGroup>
<RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>
```

When publishing a framework-dependent application, this value specifies the *minimum* version required. When publishing a self-contained application, this value specifies the *exact* version required.

### RuntimeIdentifier

The `RuntimeIdentifier` property lets you specify a single [runtime identifier (RID)](../rid-catalog.md) for the project. The RID enables publishing a self-contained deployment.
Expand Down Expand Up @@ -783,7 +813,7 @@ For more information, see [Expose .NET components to COM](../native-interop/expo
The `EnableDynamicLoading` property indicates that an assembly is a dynamically loaded component. The component could be a [COM library](/windows/win32/com/the-component-object-model) or a non-COM library that can be [used from a native host](../tutorials/netcore-hosting.md). Setting this property to `true` has the following effects:

- A *.runtimeconfig.json* file is generated.
- [Roll forward](../whats-new/dotnet-core-3-0.md#major-version-runtime-roll-forward) is set to `LatestMinor`.
- [RollForward](#rollforward) is set to `LatestMinor`.
- NuGet references are copied locally.

```xml
Expand Down
71 changes: 32 additions & 39 deletions docs/core/versions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,35 @@
---
title: How the .NET Runtime and SDK are versioned
description: This article explains how the .NET SDK and Runtime are versioned (similar to semantic versioning).
ms.date: 12/07/2020
ms.date: 07/08/2021
---

# Overview of how .NET is versioned

The [.NET Runtime and the .NET SDK](../introduction.md#sdk-and-runtimes) add new features at different frequencies. In general, the SDK is updated more frequently than the Runtime. This article explains the runtime and the SDK version numbers.

.NET releases a new major version every November. Even-numbered releases, such as .NET 6 or .NET 8, are long-term supported (LTS). Odd-numbered releases are supported until the next major release. The latest release of .NET is .NET 5.

## Versioning details

The .NET Runtime has a major/minor/patch approach to versioning that follows [semantic versioning](#semantic-versioning).
The .NET Runtime has a major.minor.patch approach to versioning that follows [semantic versioning](#semantic-versioning).

The .NET SDK doesn't follow semantic versioning. The .NET SDK releases faster and its version numbers must communicate both the aligned runtime and the SDK's own minor and patch releases.
The .NET SDK, however, doesn't follow semantic versioning. The .NET SDK releases faster and its version numbers must communicate both the aligned runtime and the SDK's own minor and patch releases.

The first two positions of the .NET SDK version number are locked to the .NET Runtime version it released with. Each version of the SDK can create applications for this runtime or any lower version.
The first two positions of the .NET SDK version number match the .NET Runtime version it released with. Each version of the SDK can create applications for this runtime or any lower version.

The third position of the SDK version number communicates both the minor and patch number. The minor version is multiplied by 100. The final two digits represent the patch number. Minor version 1, patch version 2 would be represented as 102. For example, here's a possible sequence of runtime and SDK version numbers:

| Change | .NET Runtime | .NET 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 |
| Initial release | 5.0.0 | 5.0.100 |
| SDK patch | 5.0.0 | 5.0.101 |
| Runtime and SDK patch | 5.0.1 | 5.0.102 |
| SDK feature change | 5.0.1 | 5.0.200 |

NOTES:

- If the SDK has 10 feature updates before a runtime feature update, version numbers roll into the 1000 series with numbers like 2.2.1000 as the feature release following 2.2.900. This situation isn't expected to occur.
- If the SDK has 10 feature updates before a runtime feature update, version numbers roll into the 1000 series. Version 5.0.1000 would follow version 5.0.900. This situation isn't expected to occur.
- 99 patch releases without a feature release won't occur. If a release approaches this number, it forces a feature release.

You can see more details in the initial proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository.
Expand All @@ -44,50 +46,41 @@ The optional `PRERELEASE` and `BUILDNUMBER` parts are never part of supported re

### Understand runtime version number changes

`MAJOR` is incremented when:

- Significant changes occur to the product, or a new product direction.
- Breaking changes were taken. There's a high bar to accepting breaking changes.
- An old version is no longer supported.
- A newer `MAJOR` version of an existing dependency is adopted.
- `MAJOR` is incremented once a year and may contain:

`MINOR` is incremented when:
- Significant changes in the product, or a new product direction.
- API introduced breaking changes. There's a high bar to accepting breaking changes.
- A newer `MAJOR` version of an existing dependency is adopted.

Major releases happen once a year, even-numbered versions are long-term supported (LTS) releases. The first LTS release using this versioning scheme is .NET 6, which will be released in November 2021. The latest non-LTS version is .NET 5.

- `MINOR` is incremented when:

- Public API surface area is added.
- A new behavior is added.
- A newer `MINOR` version of an existing dependency is adopted.
- A new dependency is introduced.
- Public API surface area is added.
- A new behavior is added.
- A newer `MINOR` version of an existing dependency is adopted.
- A new dependency is introduced.

`PATCH` is incremented when:
- `PATCH` is incremented when:

- Bug fixes are made.
- Support for a newer platform is added.
- A newer `PATCH` version of an existing dependency is adopted.
- Any other change doesn't fit one of the previous cases.
- Bug fixes are made.
- Support for a newer platform is added.
- A newer `PATCH` version of an existing dependency is adopted.
- Any other change doesn't fit one of the previous cases.

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.
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.PATCH` are reset to zero. When `MINOR` is incremented, `PATCH` is reset to zero while `MAJOR` remains the same.

## Version numbers in file names

The files downloaded for .NET carry the version, for example, `dotnet-sdk-2.1.300-win10-x64.exe`.
The files downloaded for .NET carry the version, for example, `dotnet-sdk-5.0.301-win10-x64.exe`.

### Preview versions

Preview versions have a `-preview[number]-([build]|"final")` appended to the version number. For example, `2.0.0-preview1-final`.
Preview versions have a `-preview.[number].[build]` appended to the version number. For example, `6.0.0-preview.5.21302.13`.

### Servicing versions

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`.

## Relationship to .NET Standard versions

.NET Standard consists of a .NET reference assembly. There are multiple implementations specific to each platform. The reference assembly contains the definition of .NET APIs which are part of a given .NET Standard version. Each implementation fulfills the .NET Standard contract on the specific platform.

The .NET Standard reference assembly uses a `MAJOR.MINOR` versioning scheme. `PATCH` level isn't useful for .NET Standard because it exposes only an API specification (no implementation) and by definition any change to the API would represent a change in the feature set, and thus a new `MINOR` version.

The implementations on each platform may be updated, typically as part of the platform release, and thus not evident to the programmers using .NET Standard on that platform.

For more information, see [.NET Standard](../../standard/net-standard.md).
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, `5.0.1-servicing-006924`.

## See also

Expand Down
Loading