Skip to content

[docs] Graduate ASPIREPIPELINES002 deployment state APIs to stable in 17.0 - #1856

Closed
aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-20816-37870376371-1-f50df3cea3e429b3
Closed

aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-20816-37870376371-1-f50df3cea3e429b3

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#20816

@mitchdenny

Target branch

Targeting release/17.0 based on the source PR milestone 17.0 (exact match found on microsoft/aspire.dev).

Why this PR is needed

microsoft/aspire#20816 graduates IDeploymentStateManager and DeploymentStateSection from experimental to stable, removing the ASPIREPIPELINES002 suppression 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 :::note callout 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 in diagnostics/aspireacadomains001.mdx for a prior graduation).
  • diagnostics/overview.mdx: Updated the ASPIREPIPELINES002 row 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 a LearnMore link back to the diagnostic page (mirrors the Azure Container Apps jobs graduation entry in whats-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.

Generated by PR Documentation Check for #20816 · copilot · auto · 81.2 AIC · ⌖ 17 AIC · ⊞ 20.4K · ◷

…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>
@aspire-repo-bot aspire-repo-bot Bot added the docs-from-code Copilot initiated issue from dotnet/aspire repo label Oct 9, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1856. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #1856 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

Copy link
Copy Markdown
Member

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: microsoft/aspire main via merged source PR microsoft/aspire#20816 (docs PR targets release/17.0; no matching branch checked).
PR status: draft, mergeable, opened 2026-10-08 (not stale)

Phase A — claims

Phase B — doc-tester

Not run; rendering of the changed pages is not browser-checked.

🤖 Posted by aspire.dev - squad (AI Agent)

Eric Erhardt (eerhardt) added a commit that referenced this pull request Nov 10, 2026
## 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>
@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 13, 2026 14:58
Copilot AI balanced review requested due to automatic review settings November 13, 2026 14:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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 ASPIREPIPELINES002 suppressions 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

@maddymontaquila

Copy link
Copy Markdown
Contributor

Superseded by #2176, which consolidates the 17.0 retired experimental diagnostics docs with a consistent format (Retired in: 17.0 badge and note, overview table, and a single What's new section).

Maddy Montaquila (maddymontaquila) added a commit that referenced this pull request Nov 16, 2026
## 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-from-code Copilot initiated issue from dotnet/aspire repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants