docs: document extension resolution algorithm and semver guidance#7836
docs: document extension resolution algorithm and semver guidance#7836wbreza merged 3 commits intoAzure:mainfrom
Conversation
Add comprehensive documentation for how azd resolves extensions from sources, including source ordering, version constraint syntax, azd version compatibility, caching behavior, and troubleshooting. Includes semantic versioning guidance for extension authors. Closes Azure#6234 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
wbreza
requested review from
JeffreyCA,
hemarina,
jongio,
rajeshkamal5050,
tg-msft,
vhvb1989 and
weikanglim
as code owners
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page explaining how azd resolves extensions and selects versions, and links it from the main extension framework doc to improve discoverability.
Changes:
- Added
extension-resolution-and-versioning.mddocumenting sources, resolution, version constraints, compatibility checks, caching, and troubleshooting. - Linked the new doc from
extension-framework.mdTable of Contents.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| cli/azd/docs/extensions/extension-resolution-and-versioning.md | New comprehensive doc for extension resolution/versioning behavior and guidance. |
| cli/azd/docs/extensions/extension-framework.md | Adds a cross-link to the new resolution/versioning doc. |
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
Several sections describe intended design rather than current implementation. The automated reviewer caught most of these - I won't repeat those. One additional gap: azd init (initializeExtensions in cmd/init.go) doesn't call resolveCompatibleExtension, so extensions installed via azure.yaml bypass azd version compatibility filtering entirely. They can end up with versions incompatible with the running azd.
The accuracy issues should be resolved before merge since this doc will be the reference users and contributors rely on.
Fix accuracy issues identified in review: - Describe interactive source prompt for multi-source conflicts - Correct version constraint behavior (CLI accepts exact/latest only) - Fix compatibility filtering to describe filter-then-warn behavior - Correct dependency resolution to same-source pinning - Document azd init limitations (no version satisfaction check) - Add cache filename sanitization details - Fix prerelease selection behavior for latest Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
wbreza
force-pushed
the
docs/extension-resolution-versioning
branch
from
e3fafae to
9f3b36f
Compare
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
The fixes in the second commit are solid. I verified each corrected section against the source code (source_manager.go, manager.go, extension.go, version_compatibility.go, registry_cache.go, init.go) and the doc now accurately reflects current behavior. One remaining gap noted inline.
- Update line 149 to note dependencies don't go through requiredAzdVersion filtering - Expand known limitations callout with explicit dependency resolution gap Addresses review feedback from jongio on Azure#7836 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Created tracking issues for the three known limitations documented in the doc:
Thanks for flagging this! |
Summary
Creates comprehensive documentation for how azd resolves extensions from configured sources, including the resolution algorithm, version constraint syntax, azd version compatibility, caching behavior, semantic versioning guidance for extension authors, and troubleshooting.
Closes #6234
Changes
cli/azd/docs/extensions/extension-resolution-and-versioning.md(298 lines) covering the full extension resolution and versioning storycli/azd/docs/extensions/extension-framework.mdto the new doc for discoverabilityDocumentation Coverage
The new document covers:
config.yaml, alphabetical ordering, and source structure^), tilde (~), range, andlatestspecifiers usingMasterminds/semver/v3requiredAzdVersioncompatibility filtering — how extensions declare minimum azd version requirements and how the resolver filters candidatesazure.yamlto installed extensionazure.yamlrequiredVersions.extensionsconfiguration — how projects pin extension versionsAZD_EXTENSION_CACHE_TTLenvironment variable overrideTesting
Documentation only — no code changes. Spell check passes with the project cspell configuration.