Container tag breaking change

docs/core/compatibility/8.0.md

@@ -104,6 +104,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 | [.NET tool roll-forward behavior](sdk/8.0/tool-rollforward.md)                  | Behavioral change                                | Preview 5  |
 | [CLI console output uses UTF-8](sdk/8.0/console-encoding.md)                    | Behavioral change/Source and binary incompatible | Preview 1  |
 | [Console encoding not UTF-8 after completion](sdk/8.0/console-encoding-fix.md)  | Behavioral change/Binary incompatible            | Preview 3  |
+| [Containers default to use the 'latest' tag](sdk/8.0/default-image-tag.md) | Behavioral change | Preview 6 |
 | ['dotnet pack' uses Release configuration](sdk/8.0/dotnet-pack-config.md)       | Behavioral change/Source incompatible            | Preview 1  |
 | ['dotnet publish' uses Release configuration](sdk/8.0/dotnet-publish-config.md) | Behavioral change/Source incompatible            | Preview 1  |
 | [MSBuild respects DOTNET_CLI_UI_LANGUAGE](sdk/8.0/msbuild-language.md)          | Behavioral change                                | Preview 5  |

docs/core/compatibility/sdk/8.0/default-image-tag.md

@@ -0,0 +1,42 @@
+---
+title: "Breaking change: Containers default to use the 'latest' tag"
+description: Learn about the breaking change in containers where .NET SDK-built containers default to use the 'latest' tag instead of '$(Version)'.
+ms.date: 07/27/2023
+---
+# Containers default to use the 'latest' tag
+
+The default image tag used for .NET SDK-built containers changed from the value of the `Version` of the project to the value `latest`.
+
+## Previous behavior
+
+Previously, the image was built with a tag value of `$(Version)`, which enabled changing the tag based on the same value that the rest of the .NET ecosystem uses.
+
+## New behavior
+
+Starting in .NET 8, the generated image has the `latest` tag in all cases.
+
+## Version introduced
+
+.NET 8 Preview 6
+
+## Type of change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change aligns the default containerization experience with the developer experiences for other container tooling like the Docker CLI. It also makes the development inner-loop of repeated container publishes easier to use with tools like Docker Compose, because the version remains stable.
+
+## Recommended action
+
+Explicitly set the version if you need it. The easiest way is to set the `ContainerImageTag` property on the command line to an explicit version, for example, `/p:ContainerImageTag=1.2.3`. But you can also programmatically set the value as you would any other MSBuild property. In a project file, you can continue to use the `$(Version)` property by adding the `ContainerImageTag` property:
+
+```xml
+<PropertyGroup>
+  <ContainerImageTag>$(Version)</ContainerImageTag>
+</PropertyGroup>
+```
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -102,6 +102,8 @@ items:
         href: sdk/8.0/console-encoding.md
       - name: Console encoding not UTF-8 after completion
         href: sdk/8.0/console-encoding-fix.md
+      - name: Containers default to use the 'latest' tag
+        href: sdk/8.0/default-image-tag.md
       - name: "'dotnet pack' uses Release configuration"
         href: sdk/8.0/dotnet-pack-config.md
       - name: "'dotnet publish' uses Release configuration"
@@ -1414,6 +1416,8 @@ items:
         href: sdk/8.0/console-encoding.md
       - name: Console encoding not UTF-8 after completion
         href: sdk/8.0/console-encoding-fix.md
+      - name: Containers default to use the 'latest' tag
+        href: sdk/8.0/default-image-tag.md
       - name: "'dotnet pack' uses Release configuration"
         href: sdk/8.0/dotnet-pack-config.md
       - name: "'dotnet publish' uses Release configuration"