Repository navigation
[docs] Note ASPIREPIPELINES004 graduation in Aspire 17.0 - #1852
aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
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 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
Asidecomponent. - Adds a note that
IPipelineOutputServiceandPipelineOutputServiceno longer triggerASPIREPIPELINES004starting 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
|
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#20814
@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#20814 graduates the pipeline output-directory API family (
IPipelineOutputServiceandPipelineOutputService) from experimental to stable, removing theASPIREPIPELINES004experimental 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:The
ASPIREPIPELINES004diagnostic 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 inaspirepipelines001.mdx,aspireazure002.mdx, andaspirecosmosdb001.mdx) stating that as of Aspire 17.0,IPipelineOutputServiceandPipelineOutputServiceare no longer experimental and don't triggerASPIREPIPELINES004, and that the diagnostic only applies to earlier versions.No other pages reference
IPipelineOutputService/GetOutputDirectory/GetTempDirectoryby 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
src/frontend/src/content/docs/diagnostics/aspirepipelines004.mdxNo new pages were created.