Docker Tag Naming and Versioning

[richlander]

.NET Core Docker images have multiple variants, of both kind and version. It is important to use an intuitive scheme to name these image variants so that users can reason about their differences without extensive documentation or other forms of decoder rings. This document defines that scheme.

Basic Form

The most basic form of .NET Core tags follows:

• [runtime-version]-[image-type]

The following are two examples of the scheme:

• 1.0.3-sdk
• 2.0.0-runtime

The remaining part of the document describes scenarios that require additional description than the basic form.

Operating System Description

Docker images are operating-system-specfic by default. The Docker client and server provide a feature called "multi-arch" which enables Dockerfiles to reference operating-system-agnostic tags. The operating-system agnostic tag form is the "basic form" described above, and is the recommended form. The multi-arch form of tags acts as an abstraction over a set of operating-system-specific images. Users may specify the operating-system-specific images if they would like, described below.

The operating-specific form of .NET Core tags follows:

• [runtime-version]-[image-type]-[operating-system]

The following are two examples of the scheme:

• 1.0.3-sdk-jessie
• 2.0.0-runtime-nanoserver

Note: It is best to describe the operating system with or as a version. In the example above, "jessie" is the common way to describe "Debian 8".

SDK Version Description

The .NET Core SDK, including the Docker images for the SDK, include one or more runtimes and a set of .NET Core Tools. There are image naming challenges with the .NET Core SDK, given the various components of the SDK, each of which has its own version number. These challenges are described below.

• .NET Core Docker images start with a runtime version, however, the .NET Core SDK can contain more than one runtime version.
• Multiple versions of the .NET Core tools may ship for a given .NET Core runtime version (before the next runtime version ships).

The following solutions will be employed for these naming challenges:

• If the SDK contains just runtime, use its version for the [runtime-version] segment of the Docker tag.
• If the SDK contains multiple runtimes, use the version of the runtime that changed in the release for the [runtime-version] segment of the Docker tag.
• If the SDK contains multiple runtimes and multiple runtimes changed for the release, use the lowest runtime version for the [runtime-version] segment of the Docker tag. The lowest version can be considered an anchor runtime version for the SDK.
• The .NET Core tools version will not show in the primary Docker tags. Instead, we'll employ a strategy like multi-arch that we can consider "multi-tools". Customers will always reference a tag like 1.0.3-sdk. It could be that 1.0.3-sdk initially was equivalent to 1.0.3-sdk-1.0.0 (with 1.0.0 being the Tools version) and then later was equivalent to 1.0.3-sdk-1.0.1. Still later, 1.0.4-sdk might ship and be equivalent to 1.0.4-sdk-1.0.1.

Given that plan, by default, customers can use either the basic or operating-system-specific forms of Docker tags for the SDK. They will get the best SDK version in both cases. However, they can reference the SDK version-specific tags if they would like to. These tags will also be operating-system-specific.

The SDK form of .NET Core tags follows:

• [runtime-version]-[image-type]-[sdk-version]-[operating-system]

The following are two examples of the scheme:

• 1.0.3-sdk-1.0.0-jessie
• 2.0.0-runtime-2.0.1-nanoserver

Previews

The runtime or the .NET Core Tools may be in preview. A preview modifier can be specific as part of the version number. See the following examples.

• 2.0.0-preview1-runtime
• 2.0.0-preview1-sdk
• 2.0.0-preview1-runtime-2.0.1-rc4-nanoserver

Short-name Tags

Short-name tags, such as 1-runime are provided as a convenience for roll-forward semantics. They are not documented as part of this proposal. They are not the primary concern and are largely self-derivable once we have the primary plan in place.