| Index | FO127 |
| Title | .NET 8 Package Versioning |
| Status | Approved |
| Authors | Dominik Viererbe, Mateus Rodrigues de Morais |
| Type | Process |
| Created | 2023-07-28 |
The dotnet8 source package should be released with a version string that contains a combination of the .NET 8 SDK and Runtime version. Binary packages that include components of the .NET SDK should use the version of the .NET SDK and binary packages that include components of the .NET Runtime should use the version of the .NET Runtime.
Users reported on Launchpad (LP: #1984451) and customers reported to Microsoft that they are confused about the version schema of Ubuntu .NET packages. Packages that contain .NET Runtime components use the version string of the SDK; a customer could be confused and think that these packages contain .NET SDK specific components, which is not the case. This is an important detail, because the .NET Runtime is a shared component between SDK feature bands (see .NET SDK & Runtime Versioning and .NET SDK feature bands).
For example, at the time of writing, these are the specific versions of the dotnet6 and dotnet7 packages:
source package dotnet6: 6.0.120-0ubuntu2
binary package aspnetcore-runtime-6.0: 6.0.120-0ubuntu2
binary package aspnetcore-targeting-pack-6.0: 6.0.120-0ubuntu2
binary package dotnet6: 6.0.120-0ubuntu2
binary package dotnet-apphost-pack-6.0: 6.0.120-0ubuntu2
binary package dotnet-host: 6.0.120-0ubuntu2
binary package dotnet-hostfxr-6.0: 6.0.120-0ubuntu2
binary package dotnet-runtime-6.0: 6.0.120-0ubuntu2
binary package dotnet-sdk-6.0: 6.0.120-0ubuntu2
binary package dotnet-sdk-6.0-source-built-artifacts: 6.0.120-0ubuntu2
binary package dotnet-targeting-pack-6.0: 6.0.120-0ubuntu2
binary package dotnet-templates-6.0: 6.0.120-0ubuntu2
binary package netstandard-targeting-pack-2.1: 6.0.120-0ubuntu2
source package dotnet7: 7.0.109-0ubuntu2
binary package aspnetcore-runtime-7.0: 7.0.109-0ubuntu2
binary package aspnetcore-targeting-pack-7.0: 7.0.109-0ubuntu2
binary package dotnet7: 7.0.109-0ubuntu2
binary package dotnet-apphost-pack-7.0: 7.0.109-0ubuntu2
binary package dotnet-host-7.0: 7.0.109-0ubuntu2
binary package dotnet-hostfxr-7.0: 7.0.109-0ubuntu2
binary package dotnet-runtime-7.0: 7.0.109-0ubuntu2
binary package dotnet-sdk-7.0: 7.0.109-0ubuntu2
binary package dotnet-sdk-7.0-source-built-artifacts: 7.0.109-0ubuntu2
binary package dotnet-targeting-pack-7.0: 7.0.109-0ubuntu2
binary package dotnet-templates-7.0: 7.0.109-0ubuntu2
binary package netstandard-targeting-pack-2.1-7.0: 7.0.109-0ubuntu2
The version strings of binary packages aspnetcore-runtime-6.0, aspnetcore-targeting-pack-6.0, dotnet-apphost-pack-6.0, dotnet-host, dotnet-hostfxr-6.0, dotnet-runtime-6.0, dotnet-targeting-pack-6.0, netstandard-targeting-pack-2.1, aspnetcore-runtime-7.0, aspnetcore-targeting-pack-7.0, dotnet-apphost-pack-7.0, dotnet-host-7.0, dotnet-hostfxr-7.0, dotnet-runtime-7.0, dotnet-targeting-pack-7.0, netstandard-targeting-pack-2.1-7.0 contain only the version of the .NET SDK (6.0.120-0ubuntu2 or 7.0.109-0ubuntu2) although they actually contain .NET Runtime components, whose version may be different.
According to Microsoft's Documentation about the versioning of .NET, Runtime-only patched releases are possible. A Runtime-only patched release would only increment the version string of the .NET Runtime. This would result in a source package and its binary packages with the same version string as the source and binary packages of the previous release. See the section Further Information for details that lower the severity of this potential conflict.
The source package and binary packages that include SDK and Runtime components MUST follow the version pattern:
{SDK-Version}-{Runtime-Version}[~{pre-release-version}]-{DEB-Revision}
Binary packages that include only SDK components MUST follow the version pattern:
{SDK-Version¹}[~{pre-release-version}]-{DEB-Revision}
¹ If Microsoft releases a Runtime-only patch that does not change {SDK-Version} a suffix +build{DIGIT} (where {DIGIT} is a number starting at 1 and incrementing with every such release) MUST be added to {SDK-Version} (e.g., "8.0.100+build1"). This SHOULD be detected automatically by comparing the current source package version with previous versions in the debian/changelog.
Binary packages that include only Runtime components MUST follow the version pattern:
{Runtime-Version²}[~{pre-release-version}]-{DEB-Revision}
² If Microsoft releases an SDK-only patch that does not change {Runtime-Version} a suffix +build{DIGIT} (where {DIGIT} is a number starting at 1 and incrementing with every such release) MUST be added to {Runtime-Version} (e.g., "8.0.0+build1"). This SHOULD be detected automatically by comparing the current source package version with previous versions in the debian/changelog.
Binary packages that include SDK and Runtime components are:
- dotnet8
Binary packages that include SDK components are:
- dotnet-templates-8.0
- dotnet-sdk-8.0
- dotnet-sdk-8.0-source-built-artifacts
Binary packages that include Runtime components are:
- dotnet-host-8.0
- dotnet-hostfxr-8.0
- dotnet-runtime-8.0
- aspnetcore-runtime-8.0
- dotnet-targeting-pack-8.0
- netstandard-targeting-pack-2.1-8.0
- aspnetcore-targeting-pack-8.0
- dotnet-apphost-pack-8.0
Runtime 8.0.0; SDK 8.0.100:
dotnet8_8.0.100-8.0.0-0ubuntu1.dsc
dotnet8_8.0.100-8.0.0-0ubuntu1.deb
dotnet-host-8.0_8.0.0-0ubuntu1.deb
dotnet-hostfxr-8.0_8.0.0-0ubuntu1.deb
dotnet-runtime-8.0_8.0.0-0ubuntu1.deb
aspnetcore-runtime-8.0_8.0.0-0ubuntu1.deb
dotnet-templates-8.0_8.0.100-0ubuntu1.deb
dotnet-sdk-8.0_8.0.100-0ubuntu1.deb
dotnet-sdk-8.0-source-built-artifacts_8.0.100-0ubuntu1.deb
dotnet-targeting-pack-8.0_8.0.0-0ubuntu1.deb
netstandard-targeting-pack-2.1-8.0_8.0.0-0ubuntu1.deb
aspnetcore-targeting-pack-8.0_8.0.0-0ubuntu1.deb
dotnet-apphost-pack-8.0_8.0.0-0ubuntu1.deb
Runtime 8.0.0.rc.1; SDK 8.0.100.rc.1:
dotnet8_8.0.100-8.0.0~rc1-0ubuntu1.dsc
dotnet8_8.0.100-8.0.0~rc1-0ubuntu1.deb
dotnet-host-8.0_8.0.0~rc1-0ubuntu1.deb
dotnet-hostfxr-8.0_8.0.0~rc1-0ubuntu1.deb
dotnet-runtime-8.0_8.0.0~rc1-0ubuntu1.deb
aspnetcore-runtime-8.0_8.0.0~rc1-0ubuntu1.deb
dotnet-templates-8.0_8.0.100~rc1-0ubuntu1.deb
dotnet-sdk-8.0_8.0.100~rc1-0ubuntu1.deb
dotnet-sdk-8.0-source-built-artifacts_8.0.100~rc1-0ubuntu1.deb
dotnet-targeting-pack-8.0_8.0.0~rc1-0ubuntu1.deb
netstandard-targeting-pack-2.1-8.0_8.0.0~rc1-0ubuntu1.deb
aspnetcore-targeting-pack-8.0_8.0.0~rc1-0ubuntu1.deb
dotnet-apphost-pack-8.0_8.0.0~rc1-0ubuntu1.deb
Runtime 8.0.0.preview.7; SDK 8.0.100.preview.7:
dotnet8_8.0.100-8.0.0~preview7-0ubuntu1.dsc
dotnet8_8.0.100-8.0.0~preview7-0ubuntu1.deb
dotnet-host-8.0_8.0.0~preview7-0ubuntu1.deb
dotnet-hostfxr-8.0_8.0.0~preview7-0ubuntu1.deb
dotnet-runtime-8.0_8.0.0~preview7-0ubuntu1.deb
aspnetcore-runtime-8.0_8.0.0~preview7-0ubuntu1.deb
dotnet-templates-8.0_8.0.100~preview7-0ubuntu1.deb
dotnet-sdk-8.0_8.0.100~preview7-0ubuntu1.deb
dotnet-sdk-8.0-source-built-artifacts_8.0.100~preview7-0ubuntu1.deb
dotnet-targeting-pack-8.0_8.0.0~preview7-0ubuntu1.deb
netstandard-targeting-pack-2.1-8.0_8.0.0~preview7-0ubuntu1.deb
aspnetcore-targeting-pack-8.0_8.0.0~preview7-0ubuntu1.deb
dotnet-apphost-pack-8.0_8.0.0~preview7-0ubuntu1.deb
Runtime-only patched releases have not been observed so far for .NET 6 and .NET 7. Furthermore, .NET 5 (source-build) had a 5.0.12.1 Runtime and 5.0.209.1 SDK release. Note the ".1" at the end of each version string. This indicates that Microsoft would follow the same strategy for future Runtime-only and SDK-only patched releases.
We have asked Microsoft to use the ".1" pattern for future SDK-only/Runtime-only patched releases that was used for the .NET 5 (source-build) 5.0.12.1 Runtime and 5.0.209.1 SDK release. They could not give us a guarantee to use this pattern, but acknowledged that Canonical could append such a suffix.
Nevertheless we will not append a ".1" suffix ourselves, because it could confuse Customers (why our version differs from the upstream version) and avoids having to ask Microsoft every release to avoid conflicts.
"Versioning for the .NET SDK works slightly differently from the .NET runtime. To align with new Visual Studio releases, .NET SDK updates sometimes include new features or new versions of components like MSBuild and NuGet. These new features or components may be incompatible with the versions that shipped in previous SDK updates for the same major or minor version.
To differentiate such updates, the .NET SDK uses the concept of feature bands. For example, the first .NET 5 SDK was 5.0.100. This release corresponds to the 3.1.1xx feature band. Feature bands are defined in the hundreds groups in the third section of the version number. For example, 5.0.101 and 5.0.201 are versions in two different feature bands while 5.0.101 and 5.0.199 are in the same feature band. When .NET SDK 5.0.101 is installed, .NET SDK 5.1.100 is removed from the machine if it exists. When .NET SDK 5.0.200 is installed on the same machine, .NET SDK 5.0.101 isn't removed."
See https://learn.microsoft.com/en-us/dotnet/core/releases-and-support#feature-bands-sdk-only.
The .NET Runtime is a shared component between feature bands and therefore has its independent versioning schema.
As the sorting order of the package versions is important you may want to read up on how the sorting algorithm works: deb-version(7). You can also use dpkg --compare-versions to compare specific version strings (e.g., dpkg --compare-versions 8.0.0~preview7-0ubuntu1 lt 8.0.0~rc1-0ubuntu1).
As RedHat and Fedora have a longer history of packaging, maintaining and delivering .NET packages it is worth a look how they version .NET packages.
Fedora seems to use the following format for its packages:
aspnetcore-runtime-6.0-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
aspnetcore-targeting-pack-6.0-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-apphost-pack-6.0-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-host-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-hostfxr-6.0-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-runtime-6.0-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-sdk-6.0-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-sdk-6.0-source-built-artifacts-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-targeting-pack-6.0-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-templates-6.0-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
netstandard-targeting-pack-2.1-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-apphost-pack-6.0-debuginfo-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-host-debuginfo-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-hostfxr-6.0-debuginfo-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-runtime-6.0-debuginfo-{.NET-Runtime-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet-sdk-6.0-debuginfo-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet6.0-debuginfo-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
dotnet6.0-debugsource-{.NET-SDK-Version}-{Revision}.{Fedora-Release}.{Arcitecture}.rpm
Examples are:
aspnetcore-runtime-6.0-6.0.20-1.fc37.x86_64.rpm
aspnetcore-targeting-pack-6.0-6.0.20-1.fc37.x86_64.rpm
dotnet-6.0.120-1.fc37.x86_64.rpm
dotnet-apphost-pack-6.0-6.0.20-1.fc37.x86_64.rpm
dotnet-host-6.0.20-1.fc37.x86_64.rpm
dotnet-hostfxr-6.0-6.0.20-1.fc37.x86_64.rpm
dotnet-runtime-6.0-6.0.20-1.fc37.x86_64.rpm
dotnet-sdk-6.0-6.0.120-1.fc37.x86_64.rpm
dotnet-sdk-6.0-source-built-artifacts-6.0.120-1.fc37.x86_64.rpm
dotnet-targeting-pack-6.0-6.0.20-1.fc37.x86_64.rpm
dotnet-templates-6.0-6.0.120-1.fc37.x86_64.rpm
netstandard-targeting-pack-2.1-6.0.120-1.fc37.x86_64.rpm
dotnet-apphost-pack-6.0-debuginfo-6.0.20-1.fc37.x86_64.rpm
dotnet-host-debuginfo-6.0.20-1.fc37.x86_64.rpm
dotnet-hostfxr-6.0-debuginfo-6.0.20-1.fc37.x86_64.rpm
dotnet-runtime-6.0-debuginfo-6.0.20-1.fc37.x86_64.rpm
dotnet-sdk-6.0-debuginfo-6.0.120-1.fc37.x86_64.rpm
dotnet6.0-debuginfo-6.0.120-1.fc37.x86_64.rpm
dotnet6.0-debugsource-6.0.120-1.fc37.x86_64.rpm
According to Omair Majid, RedHat would set the revision to a number that would avoid conflicts, if an Runtime-only patched release would occur and Microsoft does not add a ".1" suffix. For example:
- Previous Release:
- SDK-Version:
6.0.100 - Runtime-Version:
6.0.0 - Fedora Package Version:
dotnet-6.0.100-1.fc37.x86_64.rpm
- SDK-Version:
- Runtime-only patches Release (without ".1" suffix):
- SDK-Version:
6.0.100 - Runtime-Version:
6.0.1 - Fedora Package Version:
dotnet-6.0.100-2.fc37.x86_64.rpm
- SDK-Version:
Please be thorough when recording changes and progress with the spec itself and the work resulting from it. Record every meeting, attendees and conclusions from the meeting.
| Date | Status | Author(s) | Comment |
|---|---|---|---|
| 2023-07-28 | Braindump | Dominik Viererbe | Formalized result of a long discussion with
|
| 2023-07-31 | Drafting | Dominik Viererbe | Sent for review to
|
| 2023-08-01 | Pending Review | Dominik Viererbe | Copied over into a Spec Template with minor improvements from the comments of the Draft sent for review. |
| 2023-08-04 | Pending Review | Dominik Viererbe | Improvements as response to Review comments:
|
| 2023-08-04 | Pending Review | Dominik Viererbe | Update Asking Microsoft to use the ".1" suffix pattern |
| 2023-08-04 | Pending Review | Dominik Viererbe | Changed +{DIGIT} to +build{DIGIT} pattern and unnecessary explanation why two packages with the same version are a potential conflict. |
| 2023-08-05 | Approved | Dominik Viererbe | There was no Veto until the announced Deadline. |