Skip to content

CLI configuration reference: use the flat experimentalPolyglot keys #1925

Closed

Description

Part of microsoft/aspire#21115

The CLI configuration reference on release/17.0 documents the four language feature flags with a colon in the key, for example features.experimentalPolyglot:go. microsoft/aspire#20481 (merged to main) renamed them to experimentalPolyglotGo, experimentalPolyglotJava, experimentalPolyglotPython and experimentalPolyglotRust, and its description says the old colon keys no longer enable the languages. The release/17.0 branch of microsoft/aspire still reads the colon names (src/Aspire.Cli/KnownFeatures.cs L32-35 at 55867ce9d3) and the open sync PR microsoft/aspire#20570 carries the flat names (same lines at a0372fd67a), so these docs are accurate today and become wrong when that sync lands. Target branch is release/17.0; line numbers are microsoft/aspire.dev release/17.0 at 5c48cfb. microsoft/aspire.dev main (fa51b99) was also checked: the six pages cited below and src/frontend/src/data/schemas/ are identical there, so the line numbers hold on both branches.

Related: microsoft/aspire#20481 (Unify experimental polyglot AppHost feature keys), microsoft/aspire#20570 (Sync Aspire 17 release branch with main and release metadata), #1771 (closed: [docs] Unify experimental polyglot AppHost feature keys), #1809 (open draft: [docs] Document container tunnel base image configuration), #1814 (Sync Aspire CLI config schemas through 13.6.0 and fix config docs), #1924 (Document the Go AppHost: getting started, conventions and CLI references), microsoft/aspire#21106 ([Go AppHost GA] Remove the feature flag and expose Go templates), #700 (Document Go language support for polyglot AppHosts).

Checklist

  • Rename the four rows in the settings table. src/frontend/src/content/docs/reference/cli/includes/config-settings-table.md L14-17 list features.experimentalPolyglot:go, :java, :python and :rust (default false). The table is included by three pages (reference/cli/commands/aspire-config.mdx:55, reference/cli/commands/aspire-config-set.mdx:62 and reference/cli/configuration.mdx:110), so one edit fixes all of them. Fix: rename the rows to features.experimentalPolyglotGo, features.experimentalPolyglotJava, features.experimentalPolyglotPython and features.experimentalPolyglotRust, and drop the Go row instead if Remove the Go AppHost experimental feature flag aspire#21183 (open draft; removes the Go flag, tracked by [Go AppHost preview] Remove the feature flag and expose Go templates aspire#21106) lands first.
  • Remove the colon workaround from the caution block. config-settings-table.md L32-37 is a :::caution saying aspire config set cannot write keys that contain . or :. Its first bullet (L35) says that without --global the CLI writes a nested experimentalPolyglot object that later commands cannot load, and tells readers to use --global or to edit the file by hand. Unify experimental polyglot AppHost feature keys aspire#20481 was written to fix exactly that problem (its description says the flat names make aspire config set write a loadable file), so the bullet is wrong for a CLI that has the flat names. The package-ID bullet (L36) is a separate limitation and stays. Fix: delete the L35 bullet.
  • Fix the feature-flag steps on the configuration page. src/frontend/src/content/docs/reference/cli/configuration.mdx L177-178 say that some language flags "use a :<language> suffix", L184-188 show aspire config set features.experimentalPolyglot:go true --global under the title "Enable global Go support", and L190-192 say "Always set experimentalPolyglot:<language> flags with --global, or add them to the local aspire.config.json file by hand". All three describe the colon spelling. Fix: drop the suffix sentence and the always-global paragraph, and change the example to a flag that survives Remove the Go AppHost experimental feature flag aspire#21183 (or to features.experimentalPolyglotGo if that PR does not land).
  • Update the Rust get-started note. src/frontend/src/content/docs/integrations/frameworks/rust/rust-get-started.mdx L47 says a Rust AppHost is turned on with "the features.experimentalPolyglot:rust configuration setting". Fix: use features.experimentalPolyglotRust.
  • Check the Go page after Document the Go AppHost: getting started, conventions and CLI references #1924 lands. src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx L518 shows a third spelling, aspire config set features:experimentalPolyglot:go true --global (a colon after features), in the "Experimental Go AppHost templates" section (L513-532). Document the Go AppHost: getting started, conventions and CLI references #1924 rewrites that page (its head c4a58eb has no experimentalPolyglot in it) and its new go-apphost.mdx already uses the flat spelling (L11, L14 and L17), so after Document the Go AppHost: getting started, conventions and CLI references #1924 merges the site shows both spellings until this issue is done. Fix: re-run git grep experimentalPolyglot when Document the Go AppHost: getting started, conventions and CLI references #1924 merges and rename anything left.
  • Use the flat names in the AppHost-language registry if that stack is revived. The open draft Add the config-driven AppHost language foundation #1634 (and the PRs stacked on it) adds src/frontend/src/data/apphost-languages.json, whose featureFlag values use the colon spelling (experimentalPolyglot:go and the other three; L42, L56, L70 and L84 at 69e3c6b, and the same at the head of Enable every Aspire AppHost language #1638, 83dda4c). Where those values are shown to readers is unverified. Fix: use the flat names there before the registry ships.
  • Leave the per-release schema snapshots alone. Each of the 24 files src/frontend/src/data/schemas/aspire-config.13.2.0.schema.json through aspire-config.13.6.0.schema.json has four lines that mention experimentalPolyglot. Per the description of Sync Aspire CLI config schemas through 13.6.0 and fix config docs #1814 (not run), they are generated from each released CLI and never rewritten after release, so a repo-wide search will list them but they should not be edited, and a 17.x snapshot should carry the flat names without a manual edit. Fix: exclude src/frontend/src/data/schemas/ from the final search.

Recommended order

Land the docs change together with, or just after, the microsoft/aspire#20570 sync, never before it, because until then the release/17.0 CLI still reads the colon names. Do it in one pull request: the settings table and its caution, the configuration page and the Rust note first; the Go page and the registry values depend on what #1924 and the registry stack have done by then. Finish with a repo-wide search. The open draft #1809 (conflicting with release/17.0) also edits config-settings-table.md and reference/cli/configuration.mdx without touching the experimentalPolyglot text, so whichever pull request lands second re-checks the line numbers above.

Done when

git grep experimentalPolyglot on the branch finds only the historical schema snapshots and the flat names; every page uses the names the release/17.0 CLI reads; no page presents --global as a workaround for the old colon keys; and the Go flag row and examples match whatever microsoft/aspire#21183 decides.

Activity

  1. akhil9tiet commented on Oct 20, 2026

    @akhil9tiet

    I'd like to work on this — please assign it to me.

  2. IEvangelist commented on Nov 17, 2026

    @IEvangelist
    MemberAuthor

    Addressed in #2188 (merged into release/17.0).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions