Merge pull request #15 from CommunityToolkit/experimental-codes

Diagnostics doc + simplified error code
CommunityToolkit · Sep 11, 2024 · c9636ce · c9636ce
2 parents 22b556f + 4204572
commit c9636ce
Show file tree

Hide file tree

Showing 5 changed files with 19 additions and 6 deletions.
diff --git a/docs/diagnostics.md b/docs/diagnostics.md
@@ -0,0 +1,11 @@
+# .NET Aspire Community Toolkit Diagnostics
+
+Some of the API's in the .NET Aspire Community Toolkit are decorated with the [`ExperimentalAttrible`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute). This attribute is used to indicate that an API is not ready for production use and is subject to change in the future.
+
+## CTASPIRE001
+
+There are cases where there is an API provided by the .NET Aspire Community Toolkit that is an intermidiary solution until a feature is added to .NET Aspire itself. This could be a private API that is not yet ready for public consumption, or a workaround waiting for the completion of a feature in .NET Aspire.
+
+In these cases, refer to the `<remarks>` docs section of the API for more information on the feature in .NET Aspire and the issue(s) to track.
+
+Once a release of .NET Aspire with that API is available, the API in the .NET Aspire Community Toolkit will be marked as obsolete and will be removed in a future release.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,6 +8,7 @@ nav:
       - Hosting.Java: integrations/hosting-java.md
   - Contributing: contributing.md
   - Versioning and Releases: versioning.md
+  - Diagnostics: diagnostics.md
 
 plugins:
   - glightbox
@@ -53,3 +54,4 @@ markdown_extensions:
   # - pymdownx.emoji:
   # emoji_index: !!python/name:material.extensions.emoji.twemoji
   # emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
diff --git a/tests/CommunityToolkit.Aspire.Hosting.Azure.StaticWebApps.Tests/SwaHostingComponentTests.cs b/tests/CommunityToolkit.Aspire.Hosting.Azure.StaticWebApps.Tests/SwaHostingComponentTests.cs
@@ -5,7 +5,7 @@
 
 namespace CommunityToolkit.Aspire.Hosting.Azure.StaticWebApps.Tests;
 
-#pragma warning disable CTASPIRESRC001
+#pragma warning disable CTASPIRE001
 public class SwaHostingComponentTests(AspireIntegrationTestFixture<Projects.CommunityToolkit_Aspire_StaticWebApps_AppHost> fixture) : IClassFixture<AspireIntegrationTestFixture<Projects.CommunityToolkit_Aspire_StaticWebApps_AppHost>>
 {
     [Fact]

diff --git a/tests/CommunityToolkit.Aspire.Java.Hosting.EndToEndTests/JavaHostingComponentTests.cs b/tests/CommunityToolkit.Aspire.Java.Hosting.EndToEndTests/JavaHostingComponentTests.cs
@@ -4,7 +4,7 @@
 
 namespace CommunityToolkit.Aspire.Java.Hosting.EndToEndTests;
 
-#pragma warning disable CTASPIRESRC001
+#pragma warning disable CTASPIRE001
 public class JavaHostingComponentTests(AspireIntegrationTestFixture<Projects.CommunityToolkit_Aspire_Java_AppHost> fixture) : IClassFixture<AspireIntegrationTestFixture<Projects.CommunityToolkit_Aspire_Java_AppHost>>
 {
     [Theory]

diff --git a/tests/CommunityToolkit.Aspire.Testing/LoggerNotificationExtensions.cs b/tests/CommunityToolkit.Aspire.Testing/LoggerNotificationExtensions.cs
@@ -21,7 +21,7 @@ public static class LoggerNotificationExtensions
     /// <remarks>
     /// This has been copied from the Aspire.Hosting.Tests project and will likely be removed in the future.
     /// </remarks>
-    [Experimental("CTASPIRESRC001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
+    [Experimental("CTASPIRE001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
     public static Task WaitForTextAsync(this DistributedApplication app, string logText, string? resourceName = null, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(app);
@@ -41,7 +41,7 @@ public static Task WaitForTextAsync(this DistributedApplication app, string logT
     /// <remarks>
     /// This has been copied from the Aspire.Hosting.Tests project and will likely be removed in the future.
     /// </remarks>
-    [Experimental("CTASPIRESRC001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
+    [Experimental("CTASPIRE001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
     public static Task WaitForTextAsync(this DistributedApplication app, IEnumerable<string> logTexts, string? resourceName = null, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(app);
@@ -61,7 +61,7 @@ public static Task WaitForTextAsync(this DistributedApplication app, IEnumerable
     /// <remarks>
     /// This has been copied from the Aspire.Hosting.Tests project and will likely be removed in the future.
     /// </remarks>
-    [Experimental("CTASPIRESRC001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
+    [Experimental("CTASPIRE001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
     public static Task WaitForTextAsync(this DistributedApplication app, Predicate<string> predicate, string? resourceName = null, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(app);
@@ -89,7 +89,7 @@ public static Task WaitForTextAsync(this DistributedApplication app, Predicate<s
     /// <remarks>
     /// This has been copied from the Aspire.Hosting.Tests project and will likely be removed in the future.
     /// </remarks>
-    [Experimental("CTASPIRESRC001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
+    [Experimental("CTASPIRE001", UrlFormat = "https://aka.ms/communitytoolkit/aspire/diagnostics#{0}")]
     public static async Task WaitForAllTextAsync(this DistributedApplication app, IEnumerable<string> logTexts, string? resourceName = null, CancellationToken cancellationToken = default)
     {
         var table = logTexts.ToList();