Fixes breaking changes doc issues (#2619)

* Fixes breaking changes doc issues

* Fix links

* Correct front-matter

* Add index

docs/compatibility/9.0/index.md

@@ -12,7 +12,6 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 [!INCLUDE [binary-source-behavioral](../includes/binary-source-behavioral.md)]
 
 > [!NOTE]
->
 > This article is a work in progress. It's not a complete list of breaking changes in .NET Aspire 9.
 
 ## Breaking changes

docs/compatibility/9.1/container-image-name-and-tag-updates.md

@@ -0,0 +1,49 @@
+---
+title: Default container image name and tag changed
+description: Default container image name and tag changes in .NET Aspire 9.1 for AddDockerfile and WithDockerfile methods.
+ms.date: 02/13/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/2557
+---
+
+# Default container image name and tag changed
+
+In .NET Aspire 9.1, the default container image name and tag assigned to the container resource when using <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.AddDockerfile*> or <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.WithDockerfile*> changed. This change affects how container images are named and tagged by default, improving consistency and safety.
+
+## Version introduced
+
+.NET Aspire 9.1
+
+## Previous behavior
+
+In .NET Aspire 9.0:
+
+- The default container image name used was based on this format: `{ResourceName}-image-{HashOfAppHostDirectory}`
+- The default container tag used was simply `latest`
+
+## New behavior
+
+In .NET Aspire 9.1:
+
+- The default container image name used is now simply the resource name lowercased.
+- The default container tag used is now a hash derived from the app host directory combined with a timestamp of when the method was called.
+
+## Type of breaking change
+
+This change is a [behavioral change](../categories.md#behavioral-change).
+
+## Reason for change
+
+The previous behavior led to [a bug](https://github.com/dotnet/aspire/issues/7462). The resource name wasn't properly sanitized, resulting in unsafe, and unfriendly container image names. Additionally, tagging all images as `latest` made it difficult to manage and roll back deployments.
+
+## Recommended action
+
+Users should update any deployment tools, scripts, and processes to accommodate the new image names and tags.
+
+> [!NOTE]
+> The default image name and tag can be overridden by calling <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.WithImage*> and <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.WithImageTag*> on the `IResourceBuilder<ContainerResource>` respectively.
+
+## Affected APIs
+
+- <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.AddDockerfile*>
+- <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.WithDockerfile*>

docs/compatibility/9.1/cosmos-db-obsolete-apis.md

@@ -0,0 +1,55 @@
+---
+title: Cosmos DB hosting integration obsolete API and default managed identity support
+description: Breaking changes in Aspire.Hosting.Azure.CosmosDB regarding obsolete methods and default managed identity support.
+ms.date: 02/13/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/2428
+---
+
+# Cosmos DB hosting integration obsolete API and default managed identity support
+
+In .NET Aspire 9.1, the `AddDatabase()` method is obsolete and replaced by `WithDatabase()`. Additionally, `AddAzureCosmosDB()` now uses Managed Identity by default during provisioning instead of creating a Key Vault instance with a random access key.
+
+## Version introduced
+
+.NET Aspire 9.1
+
+## Previous behavior
+
+Previously, the `AddDatabase()` method was used to add a database. The `AddAzureCosmosDB()` method created a Key Vault instance with a random access key by default.
+
+## New behavior
+
+The `AddDatabase()` method is now obsolete and replaced by `WithDatabase()`. Consider the following example that uses the new API:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cosmosdb = builder.AddAzureCosmosDB("cosmos")
+                      .WithDatabase("database");
+```
+
+The `AddAzureCosmosDB()` method now uses Managed Identity by default. To revert to the previous behavior's use of key-based authentication, call `WithAccessKeyAuthentication()`:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cosmosdb = builder.AddAzureCosmosDB("cosmos")
+                      .WithAccessKeyAuthentication();
+```
+
+## Type of breaking change
+
+This change is a [source incompatible](../categories.md#source-compatibility) and [behavioral change](../categories.md#behavioral-change).
+
+## Reason for change
+
+The change follows the new API pattern when an existing resource is returned instead of a new resource (`Add` vs `With`). It also enhances security by using token credentials instead of secrets in connection strings. For more information, see [Add support for managed identity in Azure Cosmos DB hosting component](https://github.com/dotnet/aspire/pull/7092).
+
+## Recommended action
+
+Use `WithDatabase()` instead of `AddDatabase()`. Update applications to use token credentials instead of secrets in connection strings.
+
+## Affected APIs
+
+- `Aspire.Hosting.AzureCosmosExtensions.AddDatabase`

docs/compatibility/9.1/index.md

@@ -0,0 +1,25 @@
+---
+title: Breaking changes in .NET Aspire 9.1
+titleSuffix: ""
+description: Navigate to the breaking changes in .NET Aspire 9.1.
+ms.date: 02/13/2025
+---
+
+# Breaking changes in .NET Aspire 9.1
+
+If you're migrating an app to .NET Aspire 9.1, the breaking changes listed here might affect you.
+
+[!INCLUDE [binary-source-behavioral](../includes/binary-source-behavioral.md)]
+
+> [!NOTE]
+> This article is a work in progress. It's not a complete list of breaking changes in .NET Aspire 9.1.
+
+## Breaking changes
+
+| Title | Type of change | Introduced version |
+|--|--|--|
+| [Default container image name and tag changed](container-image-name-and-tag-updates.md) | Behavioral change | .NET Aspire 9.1 |
+| [Cosmos DB hosting integration obsolete API and default managed identity support](cosmos-db-obsolete-apis.md) | Source incompatible, behavioral change | .NET Aspire 9.1 |
+| [Python hosting integration parameter name changes](python-hosting-integration-api-changes.md) | Source incompatible | .NET Aspire 9.1 |
+| [Azure Service Bus hosting integration obsolete APIs](service-bus-obsolete-apis.md) | Source incompatible | .NET Aspire 9.1 |
+| [IDistributedApplicationTestingBuilder API changes](testing-builder-api-changes.md) | Binary incompatible | .NET Aspire 9.1 |

docs/compatibility/9.1/python-hosting-integration-api-changes.md

@@ -0,0 +1,40 @@
+---
+title: Python hosting integration parameter name changes
+description: Update parameter names in Python hosting integration preview for Aspire to refer to apps instead of projects.
+ms.date: 02/13/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/2559
+---
+
+# Python hosting integration parameter name changes
+
+In .NET Aspire 9.1, the Python hosting integration preview updates parameter names to refer to Python apps instead of projects. This change ensures consistent naming across the API.
+
+## Version introduced
+
+.NET Aspire 9.1
+
+## Previous behavior
+
+Some parameter names on methods and constructors in the Python hosting integration preview for .NET Aspire referred to the Python app as a `project` rather than an `app`.
+
+## New behavior
+
+Parameter names on methods and constructors in the Python hosting integration preview for .NET Aspire now refer to the Python app as an `app` instead of `project` where applicable.
+
+## Type of breaking change
+
+This change is a [source incompatible](../categories.md#source-compatibility).
+
+## Reason for change
+
+The change ensures consistent naming across the API.
+
+## Recommended action
+
+Update application source as appropriate to use the new parameter names.
+
+## Affected APIs
+
+- <xref:Aspire.Hosting.PythonAppResourceBuilderExtensions.AddPythonApp*>
+- <xref:Aspire.Hosting.Python.PythonAppResource>

docs/compatibility/9.1/service-bus-obsolete-apis.md

@@ -0,0 +1,76 @@
+---
+title: Azure Service Bus hosting integration obsolete APIs
+description: Methods AddQueue, AddTopic, and AddSubscription are being obsoleted in Azure.Hosting.ServiceBus.
+ms.date: 02/13/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/2327
+---
+
+# Azure Service Bus hosting integration obsolete APIs
+
+In .NET Aspire 9.1, the methods `AddQueue`, `AddTopic`, and `AddSubscription` are being obsoleted. This change introduces new methods that better reflect the intended usage and improve the API's clarity.
+
+## Version introduced
+
+.NET Aspire 9.1
+
+## Previous behavior
+
+Previously, the methods `AddQueue`, `AddTopic`, and `AddSubscription` were used to add resources to the Azure Service Bus.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var serviceBus = builder.AddAzureServiceBus("messaging");
+
+serviceBus.AddQueue("queueName");
+serviceBus.AddTopic("topicName");
+serviceBus.AddSubscription("topicName", "subscriptionName");
+```
+
+## New behavior
+
+The new methods use the `With` prefix to indicate that no specific resource is created, aligning with the intended usage.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var serviceBus = builder.AddAzureServiceBus("messaging");
+
+serviceBus.WithQueue(
+    name: "queueName", 
+    configure: (ServiceBusQueue queue) => { /* configure queue */ });
+
+serviceBus.WithTopic(
+    name: "topicName",
+    configure: (ServiceBusTopic topic) => { /* configure topic */ });
+```
+
+The `configure` parameter is optional. If not provided, the default configuration is used.
+
+## Type of breaking change
+
+This change is a [source incompatible](../categories.md#source-compatibility).
+
+## Reason for change
+
+A better API is provided, as the names `With` reflect that no specific resource is created. `Add` should be used when it returns an actual resource (not a resource builder). For more information, see [Add Service Bus emulator support](https://github.com/dotnet/aspire/pull/6737).
+
+## Recommended action
+
+Replace any usage of the obsolete methods with the new methods.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var serviceBus = builder.AddAzureServiceBus("messaging");
+
+serviceBus.WithQueue("queueName");
+serviceBus.WithTopic("topicName");
+```
+
+## Affected APIs
+
+- `Aspire.Hosting.AzureServiceBusExtensions.AddQueue`
+- `Aspire.Hosting.AzureServiceBusExtensions.AddTopic`
+- `Aspire.Hosting.AzureServiceBusExtensions.AddSubscription`

docs/compatibility/9.1/testing-builder-api-changes.md

@@ -0,0 +1,39 @@
+---
+title: IDistributedApplicationTestingBuilder API changes
+description: "IDistributedApplicationTestingBuilder now inherits from IDistributedApplicationBuilder, IAsyncDisposable, and IDisposable."
+ms.date: 2/13/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs-aspire/issues/2616
+---
+
+# IDistributedApplicationTestingBuilder API changes
+
+In .NET Aspire 9.1, <xref:Aspire.Hosting.Testing.IDistributedApplicationTestingBuilder> was changed to inherit from <xref:Aspire.Hosting.IDistributedApplicationBuilder>, <xref:System.IAsyncDisposable>, and <xref:System.IDisposable>. This change affects binary compatibility and requires recompilation of existing binaries.
+
+## Version introduced
+
+.NET Aspire 9.1
+
+## Previous behavior
+
+Previously, `IDistributedApplicationTestingBuilder` inherited from nothing.
+
+## New behavior
+
+`IDistributedApplicationTestingBuilder` now inherits from `IDistributedApplicationBuilder`, `IAsyncDisposable`, and `IDisposable`.
+
+## Type of breaking change
+
+This change is a [binary incompatible](../categories.md#binary-compatibility) change.
+
+## Reason for change
+
+Methods accepting a parameter of type `IDistributedApplicationBuilder` now work with `IDistributedApplicationTestingBuilder`, giving developers a consistent API surface.
+
+## Recommended action
+
+Recompile your code if necessary. If you're implementing `IDistributedApplicationTestingBuilder` yourself (which would be highly unusual), then you need to implement the new interfaces also.
+
+## Affected APIs
+
+- `IDistributedApplicationTestingBuilder`

docs/compatibility/categories.md

@@ -23,24 +23,34 @@ When behavioral changes are externally visible and modify a type's public contra
 
 ## Binary compatibility
 
+<span id="binary-incompatible"></span>
+
 Binary compatibility refers to the ability of a consumer of an API to use the API on a newer version without recompilation. Changes such as adding methods or adding a new interface implementation to a type do not affect binary compatibility. However, removing or altering an assembly's public signatures so that consumers can no longer access the same interface exposed by the assembly does affect binary compatibility. A change of this kind is termed a *binary incompatible change*.
 
 ## Source compatibility
 
+<span id="source-incompatible"></span>
+
 Source compatibility refers to the ability of existing consumers of an API to recompile against a newer version without any source changes. A *source incompatible change* occurs when a consumer needs to modify source code for it to build successfully against a newer version of an API.
 
 ## Design-time compatibility
 
+<span id="design-time-incompatible"></span>
+
 Design-time compatibility refers to preserving the design-time experience across versions of Visual Studio and other design-time environments. While this can involve the behavior or the UI of designers, the most important aspect of design-time compatibility concerns project compatibility. A project or solution must be able to be opened and used on a newer version of the design-time environment.
 
 ## Backwards compatibility
 
+<span id="backward-incompatible"></span>
+
 Backwards compatibility refers to the ability of an existing consumer of an API to run against a new version while behaving in the same way. Both behavioral changes and changes in binary compatibility affect backwards compatibility. If a consumer is not able to run or behaves differently when running against the newer version of the API, the API is *backwards incompatible*.
 
 Changes that affect backwards compatibility are discouraged, since developers expect backwards compatibility in newer versions of an API.
 
 ## Forward compatibility
 
+<span id="forward-incompatible"></span>
+
 Forward compatibility refers to the ability of an existing consumer of an API to run against an older version while exhibiting the same behavior. If a consumer is not able to run or behaves differently when run against an older version of the API, the API is *forward incompatible*.
 
 Maintaining forward compatibility virtually precludes any changes or additions from version to version, since those changes prevent a consumer that targets a later version from running under an earlier version. Developers expect that a consumer that relies on a newer API may not function correctly against the older API.

docs/compatibility/toc.yml

@@ -5,8 +5,25 @@ items:
   href: ../get-started/aspire-overview.md
 - name: Breaking changes
   href: breaking-changes.md
-- name: .NET Aspire 9.0
+- name: .NET Aspire 9.1
   expanded: true
+  items:
+  - name: Overview
+    href: 9.1/index.md
+  - name: Breaking changes in 9.1
+    expanded: true
+    items:
+    - name: Container image name and tag updates
+      href: 9.1/container-image-name-and-tag-updates.md
+    - name: Cosmos DB hosting integration obsolete API and default managed identity support
+      href: 9.1/cosmos-db-obsolete-apis.md
+    - name: Python hosting integration API changes
+      href: 9.1/python-hosting-integration-api-changes.md
+    - name: Service Bus hosting integration obsolete APIs
+      href: 9.1/service-bus-obsolete-apis.md
+    - name: Testing builder API changes
+      href: 9.1/testing-builder-api-changes.md
+- name: .NET Aspire 9.0
   items:
   - name: Overview
     href: 9.0/index.md
@@ -17,7 +34,7 @@ items:
       href: 9.0/azureopenai-ctor.md
     - name: Introduce new Python resource type and APIs changes
       href: 9.0/addpython.md
-    - name:  Updates to implicitly named volumes to avoid collisions
+    - name: Updates to implicitly named volumes to avoid collisions
       href: 9.0/unnamed-volumes.md
     - name: Make unnamed volumes more unique
       href: 9.0/make-unnamed-volumes-unique.md