Prepare issue templates for ASPIREPIPELINES001-003 diagnostics

DIAGNOSTIC-ISSUES-SUMMARY.md

@@ -0,0 +1,79 @@
+# Summary: Diagnostic Issues for PR #12416
+
+## What was done
+
+Created comprehensive documentation and templates for three new diagnostic codes introduced in [dotnet/aspire PR #12416](https://github.com/dotnet/aspire/pull/12416).
+
+## Background
+
+PR #12416 renamed and split the single `ASPIREPUBLISHERS001` diagnostic code into three sequential diagnostic codes under the ASPIREPIPELINES naming scheme. This change allows developers to selectively suppress diagnostics based on which specific experimental features they're using.
+
+## The Three New Diagnostics
+
+### ASPIREPIPELINES001 - Pipeline Infrastructure
+- **Type:** Warning  
+- **Version:** 9.2
+- **Covers:** Core pipeline infrastructure APIs including `IPipelineActivityReporter`, `IReportingStep`, `IReportingTask`, `CompletionState`, `PublishingContext`, `PublishingCallbackAnnotation`, and all types in `Aspire.Hosting.Pipelines` namespace
+
+### ASPIREPIPELINES002 - Deployment State Management
+- **Type:** Warning
+- **Version:** 9.2
+- **Covers:** Deployment state management APIs including `IDeploymentStateManager`, implementations, and `PublishingOptions.Deploy`, `.ClearCache`, `.Step` properties
+
+### ASPIREPIPELINES003 - Container Image Building  
+- **Type:** Warning
+- **Version:** 9.2
+- **Covers:** Container image building APIs including `IResourceContainerImageBuilder`, `ContainerBuildOptions`, `ContainerImageFormat`, `ContainerTargetPlatform`, and Docker/Podman runtime implementations
+
+## Files Created
+
+In `/proposed-diagnostic-issues/` directory:
+
+1. **ASPIREPIPELINES001.md** - Complete issue template data for pipeline infrastructure diagnostic
+2. **ASPIREPIPELINES002.md** - Complete issue template data for deployment state management diagnostic
+3. **ASPIREPIPELINES003.md** - Complete issue template data for container image building diagnostic
+4. **README.md** - Instructions for creating the GitHub issues manually or via CLI/API
+5. **POST-CREATION-TASKS.md** - Documentation tasks to be completed after issues are created
+
+## Next Steps
+
+### Immediate: Create GitHub Issues
+
+Someone with appropriate repository permissions needs to create three GitHub issues using the template at:
+https://github.com/dotnet/docs-aspire/issues/new?template=06-diagnostic-addition.yml
+
+The complete information for each issue is in the corresponding `.md` file in the `proposed-diagnostic-issues` directory. See the README.md in that directory for detailed instructions.
+
+### After Issues are Created: Documentation
+
+Once the issues are created and assigned, documentation pages need to be created:
+
+1. Create `/docs/diagnostics/aspirepipelines001.md`
+2. Create `/docs/diagnostics/aspirepipelines002.md`
+3. Create `/docs/diagnostics/aspirepipelines003.md`
+4. Update `/docs/diagnostics/overview.md` to include the new diagnostics
+5. Update `/docs/diagnostics/aspirepublishers001.md` with an obsolescence notice pointing to the new diagnostics
+
+See `POST-CREATION-TASKS.md` for complete details on these documentation updates.
+
+## Why This Approach?
+
+The GitHub Copilot agent cannot directly create GitHub issues due to authentication and permission constraints. Instead, this solution provides:
+
+1. **Complete, structured information** for each diagnostic in a format that matches the issue template requirements
+2. **Clear instructions** for creating the issues manually or programmatically
+3. **Documentation guidance** for the work that will follow issue creation
+4. **All necessary details** extracted from the source PR, including:
+   - Exact API lists from code changes
+   - Context from PR description
+   - Appropriate code examples
+   - Correct suppression methods
+
+This ensures that whoever creates the issues has all the information they need in a ready-to-use format.
+
+## References
+
+- **Source PR:** https://github.com/dotnet/aspire/pull/12416
+- **Issue Template:** https://github.com/dotnet/docs-aspire/issues/new?template=06-diagnostic-addition.yml
+- **Diagnostic Documentation:** https://learn.microsoft.com/dotnet/aspire/diagnostics/overview
+- **PR Discussion:** Issue #12415 in dotnet/aspire repository

proposed-diagnostic-issues/ASPIREPIPELINES001.md

@@ -0,0 +1,96 @@
+# Issue: ASPIREPIPELINES001
+
+**Issue Template:** https://github.com/dotnet/docs-aspire/issues/new?template=06-diagnostic-addition.yml
+
+## Field Values
+
+### Rule Type
+Warning
+
+### Version Introduced
+9.2
+
+### Diagnostic ID
+ASPIREPIPELINES001
+
+### Short Title
+Pipeline infrastructure APIs are experimental and subject to change
+
+### Description
+
+This diagnostic is triggered when using experimental pipeline infrastructure APIs in Aspire that provide core publishing pipeline functionality. These APIs allow developers to report progress, create steps and tasks, and track completion states during publishing operations.
+
+**APIs covered by this diagnostic:**
+
+- `IPipelineActivityReporter` - Interface for reporting pipeline activities
+- `IReportingStep` - Interface representing a publishing step that can contain multiple tasks
+- `IReportingTask` - Interface representing a publishing task within a step
+- `CompletionState` - Enum representing completion state (InProgress, Completed, CompletedWithWarning, CompletedWithError)
+- `PublishingContext` - Context object passed to publishing callbacks
+- `PublishingCallbackAnnotation` - Annotation for registering publishing callbacks on resources
+- `PipelineContext` - Context for pipeline operations
+- `PipelineStepContext` - Context for individual pipeline steps
+- All other types in the `Aspire.Hosting.Pipelines` namespace
+
+These APIs are experimental and subject to change in future releases as the publishing pipeline infrastructure matures.
+
+**Example code that triggers this diagnostic:**
+
+```csharp
+using Aspire.Hosting.ApplicationModel;
+using Aspire.Hosting.Pipelines;
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddResource(someResource)
+    .WithPublishingCallback(async (PublishingContext context) =>
+    {
+        var reporter = context.ServiceProvider.GetRequiredService<IPipelineActivityReporter>();
+        var step = await reporter.CreateStepAsync("Deploy resources");
+
+        try
+        {
+            var task = await step.CreateTaskAsync("Deploying resource...");
+            // Perform deployment
+            await task.CompleteAsync("Resource deployed", CompletionState.Completed);
+            await step.CompleteAsync("All resources deployed", CompletionState.Completed);
+        }
+        catch (Exception ex)
+        {
+            await step.CompleteAsync($"Deployment failed: {ex.Message}", CompletionState.CompletedWithError);
+        }
+    });
+```
+
+### How to fix
+
+This diagnostic is informational and indicates you're using experimental APIs. To proceed with using these APIs, suppress the diagnostic using one of the following methods:
+
+**Option 1: Suppress in .editorconfig file**
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.ASPIREPIPELINES001.severity = none
+```
+
+For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files).
+
+**Option 2: Suppress in project file**
+
+Add the following `PropertyGroup` to your project file:
+
+```xml
+<PropertyGroup>
+    <NoWarn>$(NoWarn);ASPIREPIPELINES001</NoWarn>
+</PropertyGroup>
+```
+
+**Option 3: Suppress in code using pragma directive**
+
+```csharp
+#pragma warning disable ASPIREPIPELINES001
+// Your code using pipeline infrastructure APIs
+#pragma warning restore ASPIREPIPELINES001
+```
+
+**Note:** These APIs are experimental and may change in future releases. Review the release notes when upgrading to ensure compatibility.

proposed-diagnostic-issues/ASPIREPIPELINES002.md

@@ -0,0 +1,91 @@
+# Issue: ASPIREPIPELINES002
+
+**Issue Template:** https://github.com/dotnet/docs-aspire/issues/new?template=06-diagnostic-addition.yml
+
+## Field Values
+
+### Rule Type
+Warning
+
+### Version Introduced
+9.2
+
+### Diagnostic ID
+ASPIREPIPELINES002
+
+### Short Title
+Deployment state management APIs are experimental and subject to change
+
+### Description
+
+This diagnostic is triggered when using experimental deployment state management APIs in Aspire. These APIs enable publishers to persist and retrieve deployment state between publishing operations, allowing for incremental deployments, caching, and step-by-step deployment workflows.
+
+**APIs covered by this diagnostic:**
+
+- `IDeploymentStateManager` - Interface for managing deployment state with methods to get, set, and clear state
+- `FileDeploymentStateManager` - Implementation that stores state in the file system
+- `UserSecretsDeploymentStateManager` - Implementation that stores state using user secrets
+- `DeploymentStateManagerBase` - Base class for state manager implementations
+- `PublishingOptions.Deploy` - Property to enable automatic deployment after publishing
+- `PublishingOptions.ClearCache` - Property to clear deployment state cache
+- `PublishingOptions.Step` - Property to specify a specific deployment step to execute
+
+These APIs are experimental and subject to change in future releases as deployment state management capabilities mature.
+
+**Example code that triggers this diagnostic:**
+
+```csharp
+using Aspire.Hosting.Publishing;
+
+// Configure publishing options with deployment state
+var publishingOptions = new PublishingOptions
+{
+    OutputPath = "./output",
+    Deploy = true,              // Triggers ASPIREPIPELINES002
+    ClearCache = false,         // Triggers ASPIREPIPELINES002
+    Step = "DeployToAzure"      // Triggers ASPIREPIPELINES002
+};
+
+// Use deployment state manager
+var stateManager = serviceProvider.GetRequiredService<IDeploymentStateManager>();
+await stateManager.SetStateAsync("lastDeployment", DateTime.UtcNow.ToString());
+
+var previousState = await stateManager.GetStateAsync("deploymentConfig");
+if (previousState != null)
+{
+    // Use cached state for incremental deployment
+}
+```
+
+### How to fix
+
+This diagnostic is informational and indicates you're using experimental APIs. To proceed with using these APIs, suppress the diagnostic using one of the following methods:
+
+**Option 1: Suppress in .editorconfig file**
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.ASPIREPIPELINES002.severity = none
+```
+
+For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files).
+
+**Option 2: Suppress in project file**
+
+Add the following `PropertyGroup` to your project file:
+
+```xml
+<PropertyGroup>
+    <NoWarn>$(NoWarn);ASPIREPIPELINES002</NoWarn>
+</PropertyGroup>
+```
+
+**Option 3: Suppress in code using pragma directive**
+
+```csharp
+#pragma warning disable ASPIREPIPELINES002
+// Your code using deployment state management APIs
+#pragma warning restore ASPIREPIPELINES002
+```
+
+**Note:** These APIs are experimental and may change in future releases. The shape of the state management API and the storage implementations may evolve based on feedback and requirements. Review the release notes when upgrading to ensure compatibility.

proposed-diagnostic-issues/ASPIREPIPELINES003.md

@@ -0,0 +1,114 @@
+# Issue: ASPIREPIPELINES003
+
+**Issue Template:** https://github.com/dotnet/docs-aspire/issues/new?template=06-diagnostic-addition.yml
+
+## Field Values
+
+### Rule Type
+Warning
+
+### Version Introduced
+9.2
+
+### Diagnostic ID
+ASPIREPIPELINES003
+
+### Short Title
+Container image building APIs are experimental and subject to change
+
+### Description
+
+This diagnostic is triggered when using experimental container image building APIs in Aspire. These APIs enable publishers to programmatically build container images for resources during the publishing process, supporting various image formats and target platforms.
+
+**APIs covered by this diagnostic:**
+
+- `IResourceContainerImageBuilder` - Interface for building container images from resources
+- `ContainerBuildOptions` - Class containing options for image building (format, platform, tags, labels)
+- `ContainerImageFormat` - Enum specifying the container image format:
+  - `Docker` - Docker image format
+  - `Oci` - OCI (Open Container Initiative) image format
+- `ContainerTargetPlatform` - Enum specifying the target platform:
+  - `LinuxAmd64` - Linux on x64 architecture
+  - `LinuxArm64` - Linux on ARM64 architecture
+  - `WindowsAmd64` - Windows on x64 architecture
+- `IContainerRuntime` - Interface for interacting with container runtimes
+- `DockerContainerRuntime` - Docker runtime implementation
+- `PodmanContainerRuntime` - Podman runtime implementation
+- `ContainerRuntimeBase` - Base class for container runtime implementations
+
+These APIs are experimental and subject to change in future releases as container building capabilities mature.
+
+**Example code that triggers this diagnostic:**
+
+```csharp
+using Aspire.Hosting.Publishing;
+
+// Build a container image for a resource
+var imageBuilder = serviceProvider.GetRequiredService<IResourceContainerImageBuilder>();
+
+var buildOptions = new ContainerBuildOptions
+{
+    ImageFormat = ContainerImageFormat.Oci,
+    TargetPlatform = ContainerTargetPlatform.LinuxAmd64,
+    Tags = new[] { "myapp:latest", "myapp:v1.0" },
+    Labels = new Dictionary<string, string>
+    {
+        ["version"] = "1.0.0",
+        ["description"] = "My application"
+    }
+};
+
+await imageBuilder.BuildImageAsync(myResource, buildOptions, cancellationToken);
+```
+
+Another example with Docker runtime:
+
+```csharp
+using Aspire.Hosting.Publishing;
+
+var containerRuntime = serviceProvider.GetRequiredService<IContainerRuntime>();
+
+// Check if Docker/Podman is available
+if (await containerRuntime.IsAvailableAsync())
+{
+    // Build and push image
+    await containerRuntime.BuildImageAsync(
+        contextPath: "./app",
+        dockerfilePath: "Dockerfile",
+        imageName: "myapp:latest"
+    );
+}
+```
+
+### How to fix
+
+This diagnostic is informational and indicates you're using experimental APIs. To proceed with using these APIs, suppress the diagnostic using one of the following methods:
+
+**Option 1: Suppress in .editorconfig file**
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.ASPIREPIPELINES003.severity = none
+```
+
+For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files).
+
+**Option 2: Suppress in project file**
+
+Add the following `PropertyGroup` to your project file:
+
+```xml
+<PropertyGroup>
+    <NoWarn>$(NoWarn);ASPIREPIPELINES003</NoWarn>
+</PropertyGroup>
+```
+
+**Option 3: Suppress in code using pragma directive**
+
+```csharp
+#pragma warning disable ASPIREPIPELINES003
+// Your code using container image building APIs
+#pragma warning restore ASPIREPIPELINES003
+```
+
+**Note:** These APIs are experimental and may change in future releases. The container building capabilities and API surface may evolve based on feedback and new requirements. Review the release notes when upgrading to ensure compatibility.