diff --git a/DIAGNOSTIC-ISSUES-SUMMARY.md b/DIAGNOSTIC-ISSUES-SUMMARY.md new file mode 100644 index 0000000000..27ef083b8f --- /dev/null +++ b/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 diff --git a/proposed-diagnostic-issues/ASPIREPIPELINES001.md b/proposed-diagnostic-issues/ASPIREPIPELINES001.md new file mode 100644 index 0000000000..a31db0115c --- /dev/null +++ b/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(); + 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 + + $(NoWarn);ASPIREPIPELINES001 + +``` + +**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. diff --git a/proposed-diagnostic-issues/ASPIREPIPELINES002.md b/proposed-diagnostic-issues/ASPIREPIPELINES002.md new file mode 100644 index 0000000000..05c1262688 --- /dev/null +++ b/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(); +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 + + $(NoWarn);ASPIREPIPELINES002 + +``` + +**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. diff --git a/proposed-diagnostic-issues/ASPIREPIPELINES003.md b/proposed-diagnostic-issues/ASPIREPIPELINES003.md new file mode 100644 index 0000000000..61280a2a34 --- /dev/null +++ b/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(); + +var buildOptions = new ContainerBuildOptions +{ + ImageFormat = ContainerImageFormat.Oci, + TargetPlatform = ContainerTargetPlatform.LinuxAmd64, + Tags = new[] { "myapp:latest", "myapp:v1.0" }, + Labels = new Dictionary + { + ["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(); + +// 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 + + $(NoWarn);ASPIREPIPELINES003 + +``` + +**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. diff --git a/proposed-diagnostic-issues/POST-CREATION-TASKS.md b/proposed-diagnostic-issues/POST-CREATION-TASKS.md new file mode 100644 index 0000000000..a926354e5a --- /dev/null +++ b/proposed-diagnostic-issues/POST-CREATION-TASKS.md @@ -0,0 +1,115 @@ +# Post-Issue Creation Tasks + +After the three diagnostic issues are created and the documentation files are written, the following updates will be needed: + +## 1. Update diagnostics overview + +File: `/docs/diagnostics/overview.md` + +Add these three new entries to the diagnostics table (in alphabetical order): + +```markdown +| [`ASPIREPIPELINES001`](aspirepipelines001.md) | (Experimental) Error | Pipeline infrastructure APIs are experimental and subject to change. | +| [`ASPIREPIPELINES002`](aspirepipelines002.md) | (Experimental) Error | Deployment state management APIs are experimental and subject to change. | +| [`ASPIREPIPELINES003`](aspirepipelines003.md) | (Experimental) Error | Container image building APIs are experimental and subject to change. | +``` + +Insert these entries after the `ASPIREPUBLISHERS001` entry (around line 28-29). + +## 2. Consider ASPIREPUBLISHERS001 Status + +The existing `/docs/diagnostics/aspirepublishers001.md` file documents the old `ASPIREPUBLISHERS001` diagnostic code. Since PR #12416 splits this into three new codes, consider: + +1. **Option A: Mark as obsolete** + - Add a note at the top of `aspirepublishers001.md` indicating it has been split into three new diagnostics + - Add links to the new diagnostic pages + - Keep the file for historical reference + +2. **Option B: Redirect** + - Add a redirect entry in `.openpublishing.redirection.json` from the old page to a new overview page + - Create a new page explaining the split + +3. **Option C: Update in place** + - Update the `aspirepublishers001.md` file to document all three new diagnostics + - Add a note about the diagnostic code split + +**Recommended:** Option A - mark as obsolete with clear guidance to the new diagnostics. + +## 3. Example Obsolete Notice for ASPIREPUBLISHERS001 + +Add this notice at the top of `/docs/diagnostics/aspirepublishers001.md` after the YAML frontmatter: + +```markdown +> [!IMPORTANT] +> As of Aspire 9.2, the `ASPIREPUBLISHERS001` diagnostic has been split into three more specific diagnostics: +> - [`ASPIREPIPELINES001`](aspirepipelines001.md) - Pipeline infrastructure APIs +> - [`ASPIREPIPELINES002`](aspirepipelines002.md) - Deployment state management APIs +> - [`ASPIREPIPELINES003`](aspirepipelines003.md) - Container image building APIs +> +> This allows developers to selectively suppress diagnostics based on which specific experimental features they're using. +``` + +## 4. File Naming Convention + +When creating the documentation files, follow the existing naming pattern: +- Use lowercase for the diagnostic code in filenames +- Examples: + - `aspirepipelines001.md` + - `aspirepipelines002.md` + - `aspirepipelines003.md` + +## 5. YAML Frontmatter Template + +Each documentation file should include appropriate frontmatter: + +```yaml +--- +title: Compiler Error ASPIREPIPELINESXXX +description: Learn more about compiler Error ASPIREPIPELINESXXX. [Brief description of what the diagnostic indicates]. +ms.date: [Current date in MM/DD/YYYY format] +f1_keywords: + - "ASPIREPIPELINESXXX" +helpviewer_keywords: + - "ASPIREPIPELINESXXX" +--- +``` + +## 6. Cross-references + +Consider adding cross-references between the three new diagnostic pages since they're related: + +- In ASPIREPIPELINES001: Mention the related diagnostics for state management and container building +- In ASPIREPIPELINES002: Mention the pipeline infrastructure diagnostic +- In ASPIREPIPELINES003: Mention the pipeline infrastructure diagnostic + +Example: + +```markdown +## Related diagnostics + +- [`ASPIREPIPELINES002`](aspirepipelines002.md) - Deployment state management +- [`ASPIREPIPELINES003`](aspirepipelines003.md) - Container image building +``` + +## 7. Build and Test + +After creating the documentation files: + +1. Build the documentation locally to verify there are no errors +2. Check that all internal links work correctly +3. Verify code examples are properly formatted +4. Ensure markdown lint checks pass + +## 8. PR Review Checklist + +When submitting the documentation PR: + +- [ ] All three diagnostic documentation files created +- [ ] Overview.md updated with new entries +- [ ] ASPIREPUBLISHERS001.md updated with obsolete notice +- [ ] All code examples tested for accuracy +- [ ] All markdown lint checks pass +- [ ] Build succeeds without warnings +- [ ] All internal links verified +- [ ] Appropriate ms.date values set +- [ ] Follow Microsoft Writing Style Guide conventions diff --git a/proposed-diagnostic-issues/README.md b/proposed-diagnostic-issues/README.md new file mode 100644 index 0000000000..f4fd93aaab --- /dev/null +++ b/proposed-diagnostic-issues/README.md @@ -0,0 +1,111 @@ +# Creating Diagnostic Issues + +This directory contains structured information for creating three new GitHub issues to document diagnostic codes introduced in [PR #12416](https://github.com/dotnet/aspire/pull/12416). + +## Background + +PR #12416 split the single `ASPIREPUBLISHERS001` diagnostic into three more specific diagnostics: + +1. **ASPIREPIPELINES001** - Pipeline infrastructure APIs +2. **ASPIREPIPELINES002** - Deployment state management APIs +3. **ASPIREPIPELINES003** - Container image building APIs + +This split allows developers to selectively suppress diagnostics based on which specific experimental features they're using. + +## Files in this Directory + +- `ASPIREPIPELINES001.md` - Issue data for pipeline infrastructure diagnostic +- `ASPIREPIPELINES002.md` - Issue data for deployment state management diagnostic +- `ASPIREPIPELINES003.md` - Issue data for container image building diagnostic + +## How to Create the Issues + +Each markdown file contains all the information needed to create a GitHub issue using the diagnostic addition template. + +### Option 1: Manual Issue Creation (Recommended) + +For each diagnostic file: + +1. Open the issue template: https://github.com/dotnet/docs-aspire/issues/new?template=06-diagnostic-addition.yml +2. Fill in the form fields using the values from the corresponding markdown file: + - **Rule Type**: Copy from "Rule Type" section + - **Version Introduced**: Copy from "Version Introduced" section + - **Diagnostic ID**: Copy from "Diagnostic ID" section + - **Short Title**: Copy from "Short Title" section + - **Description**: Copy from "Description" section (including code examples) + - **How to fix**: Copy from "How to fix" section (including code examples) +3. Submit the issue + +### Option 2: Using GitHub CLI (If authenticated) + +If you have GitHub CLI installed and authenticated: + +```bash +# For ASPIREPIPELINES001 +gh issue create \ + --repo dotnet/docs-aspire \ + --title "[Add diagnostics]: ASPIREPIPELINES001" \ + --label "Pri1,doc-idea,area-docs" \ + --assignee adegeo \ + --body "$(cat ASPIREPIPELINES001.md)" + +# For ASPIREPIPELINES002 +gh issue create \ + --repo dotnet/docs-aspire \ + --title "[Add diagnostics]: ASPIREPIPELINES002" \ + --label "Pri1,doc-idea,area-docs" \ + --assignee adegeo \ + --body "$(cat ASPIREPIPELINES002.md)" + +# For ASPIREPIPELINES003 +gh issue create \ + --repo dotnet/docs-aspire \ + --title "[Add diagnostics]: ASPIREPIPELINES003" \ + --label "Pri1,doc-idea,area-docs" \ + --assignee adegeo \ + --body "$(cat ASPIREPIPELINES003.md)" +``` + +**Note**: The issue template is a form-based template (YAML), so using `gh issue create` with `--body` might not work perfectly. Manual creation through the web interface is recommended. + +### Option 3: Using GitHub API + +If you're automating this with the GitHub API: + +```bash +# Example for ASPIREPIPELINES001 +curl -X POST \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.github.com/repos/dotnet/docs-aspire/issues \ + -d '{ + "title": "[Add diagnostics]: ASPIREPIPELINES001", + "body": "...", # Content from ASPIREPIPELINES001.md + "labels": ["Pri1", "doc-idea", "area-docs"], + "assignees": ["adegeo"] + }' +``` + +## Expected Outcome + +After creating these three issues: + +1. The documentation team will be notified (via assignment to @adegeo) +2. Each issue will be tracked with `Pri1`, `doc-idea`, and `area-docs` labels +3. Documentation pages will be created in `/docs/diagnostics/` directory following the pattern of existing diagnostics like `aspirepublishers001.md` +4. The new diagnostic documentation will include: + - Overview of what triggers the diagnostic + - List of affected APIs + - Code examples showing the diagnostic + - Instructions for suppressing the diagnostic + +## Related Files + +After the issues are created and documentation is written, the following files will likely be created: + +- `/docs/diagnostics/aspirepipelines001.md` - Documentation for ASPIREPIPELINES001 +- `/docs/diagnostics/aspirepipelines002.md` - Documentation for ASPIREPIPELINES002 +- `/docs/diagnostics/aspirepipelines003.md` - Documentation for ASPIREPIPELINES003 +- Updates to `/docs/diagnostics/overview.md` to include the new diagnostics + +The existing `/docs/diagnostics/aspirepublishers001.md` may need to be updated or marked as obsolete since these three new diagnostics replace it.