Skip to content

[docs] Note ASPIREPIPELINES004 graduation in Aspire 17.0 - #1852

Closed
aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-20814-37860851693-1-fdcdea9682a3958b
Closed

aspire-repo-bot[bot] wants to merge 1 commit into
release/17.0from
docs/pr-20814-37860851693-1-fdcdea9682a3958b

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Documents changes from microsoft/aspire#20814

@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#20814 graduates the pipeline output-directory API family (IPipelineOutputService and PipelineOutputService) from experimental to stable, removing the ASPIREPIPELINES004 experimental attribute and all suppressions for it across hosting, Azure deployment infrastructure, EF Core, Radius, and the linked publishing helper. The source PR's own description states:

User-facing usage

Given an IPipelineOutputService outputService and an IResource resource, the existing calls no longer require an ASPIREPIPELINES004 suppression:

var outputDirectory = outputService.GetOutputDirectory();
var resourceOutputDirectory = outputService.GetOutputDirectory(resource);
var tempDirectory = outputService.GetTempDirectory();
var resourceTempDirectory = outputService.GetTempDirectory(resource);

The ASPIREPIPELINES004 diagnostic page previously described these APIs as experimental with no indication that they later graduated. This left a documentation gap for anyone encountering the diagnostic page via search after upgrading to 17.0 and no longer seeing the warning.

What changed

  • src/frontend/src/content/docs/diagnostics/aspirepipelines004.mdx: Added an <Aside type="note"> (matching the established pattern used in aspirepipelines001.mdx, aspireazure002.mdx, and aspirecosmosdb001.mdx) stating that as of Aspire 17.0, IPipelineOutputService and PipelineOutputService are no longer experimental and don't trigger ASPIREPIPELINES004, and that the diagnostic only applies to earlier versions.

No other pages reference IPipelineOutputService/GetOutputDirectory/GetTempDirectory by name, and the diagnostics overview table's one-line description is left unchanged (consistent with how other graduated diagnostics — e.g. ASPIREAZURE002 — are still listed there verbatim).

Pages updated

  • Updated: src/frontend/src/content/docs/diagnostics/aspirepipelines004.mdx

No new pages were created.

Generated by PR Documentation Check for #20814 · copilot · auto · 54.3 AIC · ⌖ 10.6 AIC · ⊞ 20.4K · ◷

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 8, 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 #1852. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #1852 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#20814 (docs PR targets release/17.0; no matching branch checked).
PR status: draft, mergeable, opened 2026-10-08 (not stale)

Phase A — claims

  • ✅ verified: [Experimental("ASPIREPIPELINES004")] removed from IPipelineOutputService and PipelineOutputService; all pragmas removed.

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 were identified for the documentation update clarifying the Aspire 17.0 API stability boundary.

No open issues 🎉

What changed in this PR

Updates the pipeline output service diagnostic page to explain its graduation to stable APIs in Aspire 17.0.

Changes:

  • Imports Starlight’s Aside component.
  • Adds a note that IPipelineOutputService and PipelineOutputService no longer trigger ASPIREPIPELINES004 starting in 17.0, while retaining guidance for earlier versions.
File Description
src/​frontend/​src/​content/​docs/​diagnostics/​aspirepipelines004.mdx Clarifies the version boundary for the experimental diagnostic.

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