Repository navigation
[docs] Graduate ASPIREPIPELINES002 deployment state APIs to stable in 17.0 - #1856
aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
…17.0 Documents the graduation of IDeploymentStateManager and DeploymentStateSection from experimental to stable, matching microsoft/aspire#20816. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
docs-pr-reviewer report — [partial — phase A: all extracted claims evaluated; phase B: not run (docs site was not served in this automated run)]Recommendation: approve Source used: Phase A — claims
Phase B — doc-testerNot run; rendering of the changed pages is not browser-checked. 🤖 Posted by aspire.dev - squad (AI Agent) |
## Summary Documents the 17.0 feature "Detect drift in generated pipeline output" from microsoft/aspire#21681 (fixes microsoft/aspire#18833). - Adds [`deployment/output-diffing.mdx`](src/frontend/src/content/docs/deployment/output-diffing.mdx): why and when to use it, enabling `WithOutputDiffing`, running `aspire do publish-and-diff`, reading `Added`/`Changed`/`Removed` results and fixing drift, a GitHub Actions example, comparing other steps, `Pipeline:OutputDiff` configuration (ordered include/exclude rules and `Auto`/`Git`/`FileSystem` mode), how Git and filesystem comparison work, capture timing, and C#-only custom `IPipelineOutputSnapshotter<TSnapshot>` / `IPipelineOutputComparer<TSnapshot>` extensibility. Includes a sidebar entry with all locale translations. - Adds the `ASPIREPIPELINES005` diagnostic page, overview table row, and sidebar entry. - Cross-links from the pipelines overview, CI/CD overview (new section and card), Docker Compose output artifacts, and the `aspire do` and `aspire publish` CLI reference pages. - AppHost samples use synced TypeScript-then-C# tabs. `withOutputDiffing` is exported to the TypeScript AppHost SDK; the factory and generic overloads, options-pattern configuration, and custom snapshotter/comparer are C#-only, with a note beside each operation. The 17.0 what's-new page is intentionally not touched. ### Assumptions and notes - The PR description shows `builder.Pipeline.WithOutputDiffing()` and mentions `IPipelineOutputDiffer` / `IPipelineOutputFileHasher`. The merged code on `release/17.0` and `main` exposes `builder.WithOutputDiffing()` (an extension on `IDistributedApplicationBuilder`), and the public extension points are the snapshotter and comparer interfaces. The hasher is internal. The docs follow the merged code and docs/specs/pipeline-output.md. - `ASPIREPIPELINES005` is documented as an error because a C# AppHost build reports `error ASPIREPIPELINES005` until suppressed (verified). The product repo's docs/list-of-diagnostics.md lists it as a warning. - The checked-in API reference data stops at 13.6, so the new APIs are inline code rather than `ApiReference` links, and the TypeScript blocks have no `twoslash` meta (the generated type bundle doesn't contain `withOutputDiffing`). The TypeScript samples were type-checked against a generated SDK instead (see Validation). - No open docs PR covers this feature. #1852 and #1856 (diagnostic graduations) and #2035 (pipelines page) edit nearby files but different content; this PR doesn't duplicate or contradict them. ## Third-party links and affiliations None. ## Validation Documentation behavior was verified against a dev Aspire CLI (`17.1.0-preview.1.26556.5`, a `main` build that contains #21681; the output diffing source is identical on `release/17.0`) using C# file-based and TypeScript AppHosts with a Docker Compose environment: - `aspire do publish-and-diff` with no committed output: failed with `Added: docker-compose.yaml`, exit code 6. - Same command after committing output: succeeded (10/10 steps). - After tampering with the committed file or changing the AppHost: failed with `Changed: docker-compose.yaml`; the regenerated file was left on disk and `git diff` showed it. - `aspire do publish` after tampering: generation only, no comparison. - A custom step deleting a tracked file reported `Removed:`; a custom `targetStep`/`diffStepName` worked; two comparison targets coexisted; `--output-path` moved the compared directory. - Git-ignored output in `Auto` mode was not compared (passed silently); `Mode=FileSystem` detected it. `Mode=Git` outside a worktree failed with "Git is required to capture pipeline output...". A stale untracked file that generation doesn't touch was not reported. - `Pipeline:OutputDiff` rules and mode worked from `appsettings.json` (C# and TypeScript AppHosts) and from `Pipeline__OutputDiff__*` environment variables; invalid actions failed with "Output diff rule actions must be Include or Exclude." - All C# samples from the new page compiled together with `dotnet build apphost.cs`; the TypeScript samples passed `npx tsc -p tsconfig.apphost.json --noEmit` against the generated SDK. Repository checks (from `src/frontend`): - `pnpm install --frozen-lockfile --prefer-offline`: passed. - `pnpm exec astro sync`: passed. - `pnpm exec vitest run --config vitest.config.ts tests/unit/seo-lengths.vitest.test.ts tests/unit/apphost-examples.vitest.test.ts tests/unit/typescript-first-apphost-tabs.vitest.test.ts tests/unit/aspire-version-placeholders.vitest.test.ts tests/unit/page-metadata.vitest.test.ts tests/unit/redirects.vitest.test.ts tests/unit/twoslash-blocks.vitest.test.ts tests/unit/filetree-format.vitest.test.ts`: 8 files, 93 tests passed. - `pnpm test:unit:twoslash-blocks`: passed. - `pnpm exec eslint config/sidebar/deployment.topics.ts config/sidebar/reference.topics.ts` and `pnpm exec prettier --check` on the same files: passed. - Rendered the new pages with `pnpm exec astro dev` and checked them with `playwright-cli` (HTTP 200, tabs, tables, steps, and the new sidebar entry). - Not run: `pnpm build` (CI only, per repository policy). --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Matt Kotsenas <MattKotsenas@users.noreply.github.com>
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the documentation updates covering the APIs’ graduation in Aspire 17.0.
No open issues 🎉
What changed in this PR
Documents the graduation of IDeploymentStateManager and DeploymentStateSection to stable APIs in Aspire 17.0, aligning the diagnostic guidance and release notes with the upstream change.
Changes:
- Clarifies that Aspire 17.0+ users can remove
ASPIREPIPELINES002suppressions while retaining guidance for earlier versions. - Updates the diagnostics index to reflect the graduation.
- Adds release notes with a usage example and confirms that signatures, defaults, and persistence behavior remain unchanged.
| File | Description |
|---|---|
src/frontend/src/content/docs/whats-new/aspire-17.mdx |
Adds the API graduation announcement and usage example. |
src/frontend/src/content/docs/diagnostics/overview.mdx |
Records the 17.0 graduation in the diagnostics table. |
src/frontend/src/content/docs/diagnostics/aspirepipelines002.mdx |
Adds the graduation notice and version-specific suppression guidance. |
Review effort: Balanced
|
Superseded by #2176, which consolidates the 17.0 retired experimental diagnostics docs with a consistent format ( |
## Summary <!-- Describe what this pull request changes and why. --> Consolidates the retired experimental diagnostic documentation for Aspire 17.0, superseding the individual PRs against `release/17.0`. - Marks 14 diagnostic pages as retired in 17.0, retaining their historical content and guidance for removing suppressions. - Updates the diagnostics overview and the 17.0 release notes, including `ASPIREDENO001` and `ASPIRECONNECTIONSTRINGS001`, which don't have dedicated pages. - Explains that `ASPIRECOMPUTE002` was only partially graduated: endpoint-mapping contracts are stable, while persistent-volume APIs remain experimental. - Removes retired suppressions and experimental cautions from affected guides, while retaining the experimental image-building guidance for `ASPIREPIPELINES003`. - Notes that `ASPIRECSHARPAPPS001` was retired when `AddCSharpApp` became obsolete. The broader migration and ProjectResource v2 guidance is separate in #2180. The retired diagnostic list was checked against `[Experimental("…")]` usages in `microsoft/aspire` between `v13.6.5` and `release/17.0`. Supersedes #1846, #1847, #1851, #1852, #1853, #1854, #1856, #1857, #2127, #2167, #2168, #2169, #2170, #2171. ## Third-party links and affiliations <!-- List any third-party links added or changed by this pull request and disclose any material affiliation with the linked organizations, such as employment, sponsorship, or ownership. Write "None" if this pull request doesn't add or change third-party links. --> None ## Validation <!-- List the checks you ran or explain why validation isn't needed. --> - `git diff --check origin/release/17.0 -- src/frontend/src/content/docs` — passed. - Frontend validation CI — passed; frontend build CI is pending. - Local Astro build and tests were not run; Bun and frontend dependencies were unavailable. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Documents changes from microsoft/aspire#20816
@mitchdennyTarget branch
Targeting
release/17.0based on the source PR milestone17.0(exact match found onmicrosoft/aspire.dev).Why this PR is needed
microsoft/aspire#20816 graduates
IDeploymentStateManagerandDeploymentStateSectionfrom experimental to stable, removing theASPIREPIPELINES002suppression requirement. The source PR's body includes a "User-facing usage" section showing that existing usage (AcquireSectionAsync/SaveSectionAsync) no longer requires suppressing the diagnostic, and describes removing 43 obsolete warning suppressions across Hosting, Azure/AKS/Sandboxes, Kubernetes, Docker, and their tests. All signatures, defaults, and persistence/migration behavior are unchanged — this is an attribute-only graduation, not an API redesign.Summary of documentation changes
diagnostics/aspirepipelines002.mdx: Added a:::notecallout stating the APIs graduated from experimental in Aspire 17.0, and updated the "To correct this error" section to tell 17.0+ users they can remove existing suppressions (mirrors the pattern used indiagnostics/aspireacadomains001.mdxfor a prior graduation).diagnostics/overview.mdx: Updated theASPIREPIPELINES002row in the diagnostics table to note the 17.0 graduation.whats-new/aspire-17.mdx: Added a new "🚀 Pipelines and deployment" section describing the graduation, with a short code sample copied from the source PR's "User-facing usage" snippet, and aLearnMorelink back to the diagnostic page (mirrors the Azure Container Apps jobs graduation entry inwhats-new/aspire-13-4.mdx).Files modified
src/frontend/src/content/docs/diagnostics/aspirepipelines002.mdx(updated)src/frontend/src/content/docs/diagnostics/overview.mdx(updated)src/frontend/src/content/docs/whats-new/aspire-17.mdx(updated)No new pages were created; all changes update existing pages in place.