Rename azd extension/tool UPGRADE commands to UPDATE - #9370
Open
hyoshis wants to merge 13 commits into
Open
Conversation
Rename the user-facing 'azd extension upgrade' and 'azd tool upgrade' commands to 'update', keeping 'upgrade' as a cobra alias for backward compatibility. Update all displayed help text, flag descriptions, prompts, progress and summary messages, error strings, docs, and regenerate usage/figspec snapshots. Go identifiers, telemetry field-key constants, and the --no-dependency-upgrades flag name are unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Adds two sets of UX guidance to the azd style guides: 1. Responsive list/table layouts for list commands, documented as part of the core azd design patterns in azd-style-guide.md. 2. Agentic (AI / GitHub Copilot) UX patterns, moved into a dedicated agentic-ux-style-guide.md so the core guide focuses solely on core azd design patterns (which extensions may follow for consistency, but are not enforced). Adds cross-references in the core guide's overview and in cli/azd/AGENTS.md so agents reference the correct file for the flow they're working on. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 656aee2e-29aa-4b53-965c-63543c1dd44a
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: be625a8a-0787-45ea-b3d9-a782d4c2651f
hyoshis
requested review from
JeffreyCA,
RickWinter,
hemarina,
richardpark-msft,
tg-msft and
vhvb1989
as code owners
July 30, 2026 18:36
|
Azure Pipelines: Successfully started running 1 pipeline(s). 21 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
Contributor
There was a problem hiding this comment.
Pull request overview
Renames extension/tool upgrade commands to update while retaining aliases, and refreshes related UX, documentation, tests, and snapshots.
Changes:
- Adds canonical
extension updateandtool updatecommands. - Updates user-facing terminology and generated snapshots.
- Adds broader CLI and agentic UX guidance.
Show a summary per file
| File | Description |
|---|---|
docs/guides/creating-an-extension.md |
Updates promotion guidance. |
cli/azd/docs/style-guidelines/azd-style-guide.md |
Adds responsive-layout guidance. |
cli/azd/docs/style-guidelines/agentic-ux-style-guide.md |
Adds agentic UX guidance. |
cli/azd/docs/extensions/extension-resolution-and-versioning.md |
Updates extension commands and terminology. |
cli/azd/docs/extensions/extension-framework.md |
Documents extension update and alias. |
cli/azd/cmd/tool.go |
Renames the tool command and output. |
cli/azd/cmd/tool_test.go |
Updates expected result messages. |
cli/azd/cmd/testdata/TestUsage-azd-tool.snap |
Updates tool command listing. |
cli/azd/cmd/testdata/TestUsage-azd-tool-update.snap |
Captures update-command help. |
cli/azd/cmd/testdata/TestUsage-azd-tool-check.snap |
Updates check help wording. |
cli/azd/cmd/testdata/TestUsage-azd-extension.snap |
Updates extension command listing. |
cli/azd/cmd/testdata/TestUsage-azd-extension-update.snap |
Captures update-command help. |
cli/azd/cmd/testdata/TestFigSpec.ts |
Updates completion specifications. |
cli/azd/cmd/extension.go |
Renames extension command and output. |
cli/azd/cmd/extension_upgrade_test.go |
Updates failure assertions. |
cli/azd/cmd/extension_test.go |
Updates summary assertions. |
cli/azd/CHANGELOG.md |
Records the command rename. |
cli/azd/AGENTS.md |
References expanded UX guidance. |
Review details
Comments suppressed due to low confidence (1)
cli/azd/cmd/tool.go:1537
- Changing this value to
updatechanges the serializedactionfield in--dry-run --output json; the normal update path makes the same change at line 1362. Existing automation invoking the backward-compatibleupgradealias can therefore break even though the command still resolves. Decouple the human-facing verb from the stable JSON value, or explicitly version and document this machine-output contract change.
action := "update"
- Files reviewed: 18/18 changed files
- Comments generated: 6
- Review effort level: Medium
3 tasks
vhvb1989
approved these changes
Jul 31, 2026
jongio
reviewed
Jul 31, 2026
jongio
left a comment
jongio
left a comment
Member
There was a problem hiding this comment.
Two of the failing CI checks trace directly to this diff, and both are quick fixes.
golangci-lint fails with a single issue: cmd/extension.go:1061:1: File is not properly formatted (gofmt). The reindented return in the dependency-upgrade error path lost a tab. Inline suggestion below.
cspell fails on tabwriter at docs/style-guidelines/azd-style-guide.md:308, :375, and :422. Those lines come from the new responsive-table section in this PR, so the word needs to go in the cspell dictionary (or be wrapped so cspell skips it). Inline comment below.
Two smaller things that don't block:
--docs builds its deep link from c.CommandPath() (cmd/cobra_builder.go), so azd extension update --docs and azd tool update --docs now resolve to https://learn.microsoft.com/azure/developer/azure-developer-cli/reference#azd-extension-update and #azd-tool-update. Cobra reports the canonical path for alias invocations too, so azd extension upgrade --docs lands on the new anchor as well. Is the learn.microsoft.com reference page regenerated from this repo automatically, or does that anchor need a separate docs PR? Right now both the new name and the old alias point at an anchor that doesn't exist yet.
cli/azd/extensions/azure.coding-agent/README.md:32 still tells users to run azd extension upgrade azure.coding-agent. It keeps working via the alias, but it's user-facing copy in the same rename scope.
Address review feedback, complete customer-facing terminology updates, preserve compatibility, and remove unrelated documentation changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21cd8119-a644-4b3c-8c99-3f89f63a9968
hyoshis
requested review from
glharper,
huimiu,
hund030,
therealjohn,
trangevi and
trrwilson
as code owners
August 1, 2026 03:45
github-actions
Bot
added
ext-agents
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21cd8119-a644-4b3c-8c99-3f89f63a9968
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21cd8119-a644-4b3c-8c99-3f89f63a9968
Contributor
There was a problem hiding this comment.
Review details
Suppressed comments (6)
cli/azd/CHANGELOG.md:7
- azd-code-reviewer: This changelog entry should be deferred to the release/version-bump PR.
cli/azd/AGENTS.md:232says feature changes generally should not updateCHANGELOG.md, and this PR is not preparing a release.
- Rename the `azd extension upgrade` and `azd tool upgrade` commands to `azd extension update` and `azd tool update`. The former `upgrade` names continue to work as aliases for backward compatibility.
docs/specs/metrics-audit/telemetry-schema.md:20
- azd-code-reviewer: This updates only the event description, but the authoritative schema still calls these operations “upgrade” throughout the extension fields (lines 207–216) and tool-management section (lines 288–327). Update those headings, field labels, and descriptions to “update” while retaining the stable
*.upgrade.*keys; otherwise the telemetry docs use conflicting terminology for the renamed commands.
docs/specs/metrics-audit/feature-telemetry-matrix.md:33 - azd-code-reviewer: The extension row immediately above still says
extension.source.kindapplies tolist/show/install/upgrade, while the detailed row now usesupdate. Use the canonical command name consistently here; keep only the stable telemetry keys asupgrade.
cli/azd/extensions/azure.coding-agent/README.md:32 - azd-code-reviewer: The introductory sentence still tells users they “want to upgrade” immediately before showing the new
updatecommand, and it is missing “have.” Align the prose with the renamed command to avoid a contradictory example.
azd extension update azure.coding-agent
cli/azd/docs/extensions/extension-framework.md:1214
- azd-code-reviewer: This guide still describes
requiredAzdVersionfiltering as “install/upgrade” on line 1095 and dependency resolution as “installs or upgrades” on line 1191. Update those remaining operation descriptions so this user-facing guide consistently uses the new command vocabulary.
Pack manifests must include at least one dependency. They may omit `capabilities`, `namespace`, `entryPoint`, `usage`, and `examples` when the pack has no commands of its own. Installing a pack installs its dependencies recursively from the same extension source as the pack. Dependency versions in the manifest support semver constraints, but command-line `--version` values for `azd extension install` and `azd extension update` are exact versions.
cli/azd/pkg/tool/installer.go:1407
- azd-code-reviewer:
runSkillAgentCommandstill sets its operation verb to"upgrade"at line 1932, so a missing plugin update command now surfacesagent … has no upgrade command configuredfrom line 1936. Change that diagnostic verb to"update"so this error path matches the renamed command and the other updated error strings.
- Files reviewed: 45/45 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21cd8119-a644-4b3c-8c99-3f89f63a9968
Contributor
There was a problem hiding this comment.
Review details
Suppressed comments (6)
cli/azd/pkg/tool/installer.go:1153
- [azd-code-reviewer] The rename is incomplete in this file:
runSkillAgentCommandat lines 1929-1937 still builds the user-facing erroragent %q has no upgrade command configured. Anazd tool updatefailure can therefore still surface the old verb. Change that display verb toupdatewhile retaining internal upgrade identifiers.
docs/specs/metrics-audit/feature-telemetry-matrix.md:35 - [azd-code-reviewer] This matrix update misses the Extensions summary at line 33, which still says
extension.source.kindapplies tolist/show/install/upgrade. Change that command reference tolist/show/install/update; theext.upgradeevent andextension.upgrade.*keys should remain unchanged.
cli/azd/extensions/azure.coding-agent/README.md:32 - [azd-code-reviewer] The command was updated, but its lead-in still says “want to upgrade” and is missing “have” (“if you already the extension installed”). Update the sentence too so the example is grammatical and uses the new vocabulary.
azd extension update azure.coding-agent
cli/azd/docs/extensions/extension-framework.md:1214
- [azd-code-reviewer] The extension framework still uses the old current-operation terminology in several places, including
install/upgradeforrequiredAzdVersion(line 1095), “installs or upgrades” for dependency resolution (line 1191), and the “Version Upgrade Path” section (lines 772-806). Update this prose to match the renamed command while leaving historical references and stable identifiers unchanged.
Pack manifests must include at least one dependency. They may omit `capabilities`, `namespace`, `entryPoint`, `usage`, and `examples` when the pack has no commands of its own. Installing a pack installs its dependencies recursively from the same extension source as the pack. Dependency versions in the manifest support semver constraints, but command-line `--version` values for `azd extension install` and `azd extension update` are exact versions.
cli/azd/CHANGELOG.md:7
- Feature and fix PRs generally defer changelog edits to the release/version-bump workflow to avoid conflicts (
cli/azd/AGENTS.md:235-243). This PR is not preparing a release, so remove this entry and let release tooling add it later.
### Other Changes
- Rename the `azd extension upgrade` and `azd tool upgrade` commands to `azd extension update` and `azd tool update`. The former `upgrade` names continue to work as aliases for backward compatibility.
docs/specs/metrics-audit/telemetry-schema.md:20
- [azd-code-reviewer] The schema is still internally inconsistent: line 19 says “install/upgrade event,” and lines 207-216 plus 288-327 describe current extension/tool operations as “upgrade” in prose and section titles. Rename those labels and descriptions to “update” while retaining stable OTel keys and enum values such as
extension.upgrade.*andupgraded.
- Files reviewed: 46/46 changed files
- Comments generated: 2
- Review effort level: Balanced
jongio
approved these changes
Aug 3, 2026
jongio
left a comment
jongio
left a comment
Member
There was a problem hiding this comment.
Two notes inline: a changelog wording suggestion about JSON output, and a correction on the lifecycle hooks concern raised earlier on this PR.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21cd8119-a644-4b3c-8c99-3f89f63a9968
Contributor
There was a problem hiding this comment.
Review details
Suppressed comments (4)
cli/azd/cmd/extension.go:2595
- The user-facing rename is incomplete for skipped dependency rows. This line appends
child.SkipReason, andpkg/extensions/manager.go:1159still producesdependency upgrades disabled; ... available, soazd extension update --no-dependency-upgradescontinues to display the old verb. Update that source string and its assertions to saydependency updates disabled.
"%s%s Updating %s dependency",
cli/azd/extensions/azure.coding-agent/README.md:29
- The sentence introducing this updated command still says users “want to upgrade” and is missing “have,” leaving this README inconsistent with the new command vocabulary. Update the introduction along with the command example.
azd extension update azure.coding-agent
docs/specs/metrics-audit/feature-telemetry-matrix.md:33
- The command inventory is still inconsistent: the Extensions row above this updated Tool row lists
extension list/show/install/upgrade. Change that command-facing reference toupdate; theext.upgradeevent andextension.upgrade.*keys should remain unchanged.
docs/specs/metrics-audit/telemetry-schema.md:20 - The telemetry schema terminology update is incomplete. Line 19 still calls
ext.installan install/upgrade event, lines 207-216 describe extension updates as upgrades, and lines 288, 312, and 320-327 still describe theazd toolcommand asupgrade. Update those command-facing headings and descriptions to “update” while retaining the intentionally stableext.upgradeandtool.upgrade.*keys.
- Files reviewed: 48/48 changed files
- Comments generated: 0 new
- Review effort level: Balanced
jongio
approved these changes
Aug 4, 2026
JeffreyCA
reviewed
Aug 4, 2026
Contributor
There was a problem hiding this comment.
I think we can go a bit further and use update everywhere in the code and output, and keep upgrade only where we really need backward compatibility.
Specifically, I think we can:
- Rename all Go identifiers, exported APIs, interfaces, tests, and filenames that belong to these extension and tool update flows from
UpgradetoUpdate. I don't see any external consumers using those exported APIs. - Rename telemetry to
ext.update,tool.update.*, and the matchingUpdateconstants. The command span names (cmd.extension.update) already change, so keeping the old telemetry names would leave us with mixed terms. - Rename
extension updateJSON from"upgraded"to"updated","upgraded"counts to"updated", anddependencyUpgradestodependencyUpdates. - Rename
tool updateJSON, including--dry-run, from"action": "upgrade"to"action": "update". - Add
--no-dependency-updatesas the new flag while keeping--no-dependency-upgradesas a hidden alias for existing scripts. - Keep
azd extension upgradeandazd tool upgradeas command aliases. - Keep
upgradefor terms owned by other tools or protocols, such ashelm upgrade, package-manager or pipupgradearguments, WebSocket upgrades, existing URLs, etc.
The JSON changes only affect extension update -o json, extension update --all -o json, and the matching tool update result and dry-run output, which I think this is an acceptable break - I don't see any occurrences users running azd ext upgrade or azd tool upgrade with --output json in our telemetry.
I also think we can also remove the hook compatibility change. The extension and tool commands do not use HooksMiddleware, so those old hook names never worked. The middleware change affects other commands and is not needed for this rename.
Member
|
@JeffreyCA I agree on dropping the hook compatibility change, and I think the case is stronger than "those names never worked".
So it isn't only that Dropping Unrelated to the code: the failing |
This reverts commit 87298c1.
Contributor
There was a problem hiding this comment.
Review details
Suppressed comments (5)
docs/specs/metrics-audit/feature-telemetry-matrix.md:33
- The adjacent extension inventory still ends with
list/show/install/upgrade, leaving this telemetry matrix inconsistent with the canonical command name used elsewhere in the same table. Change only the command reference; keep theext.upgradeevent andextension.upgrade.*keys stable.
docs/specs/metrics-audit/telemetry-schema.md:20 - This event description now uses “update,” but the authoritative schema remains internally stale: lines 19 and 207–216 describe extension installs/fields as upgrades, and lines 288, 312, and 320–327 still describe
tool upgrade. Update those descriptive labels and notes while retaining the compatibility keys (ext.upgrade,extension.upgrade.*,tool.upgrade.*) and stable enum values.
cli/azd/docs/extensions/extension-framework.md:1214 - Earlier sections of this same guide still say azd filters versions during “install/upgrade” (line 1095) and “installs or upgrades” dependencies (line 1191). Update those operational references so the guide consistently uses the new canonical verb; the explicit backward-compatibility alias note should remain unchanged.
Pack manifests must include at least one dependency. They may omit `capabilities`, `namespace`, `entryPoint`, `usage`, and `examples` when the pack has no commands of its own. Installing a pack installs its dependencies recursively from the same extension source as the pack. Dependency versions in the manifest support semver constraints, but command-line `--version` values for `azd extension install` and `azd extension update` are exact versions.
cli/azd/CHANGELOG.md:7
- Repository guidance defers core
CHANGELOG.mdentries to release/version-bump PRs (cli/azd/AGENTS.md:240), and this command-rename PR is not release preparation. Remove this entry so it can be added by the release process.
- Rename the `azd extension upgrade` and `azd tool upgrade` commands to `azd extension update` and `azd tool update`. The former `upgrade` names continue to work as aliases for backward compatibility.
cli/azd/extensions/azure.coding-agent/README.md:29
- The sentence introducing this command still says “want to upgrade” and is missing “have,” so this README mixes the old and new vocabulary. Rewrite the sentence to use “update” consistently.
azd extension update azure.coding-agent
- Files reviewed: 46/46 changed files
- Comments generated: 0 new
- Review effort level: Balanced
hyoshis
commented
Aug 4, 2026
| { | ||
| name: ['upgrade'], | ||
| description: 'Upgrade installed extensions to the latest version.', | ||
| name: ['update', 'upgrade'], |
Contributor
Author
There was a problem hiding this comment.
these are snapshots generated after commands are changed.
linux insturction:
UPDATE_SNAPSHOTS=true go test ./cmd -run 'TestFigSpec|TestUsage'
Contributor
Author
There was a problem hiding this comment.
$env:UPDATE_SNAPSHOTS='true'; go test ./cmd -run 'TestFigSpec|TestUsage'
Windows
Contributor
Author
There was a problem hiding this comment.
thsi file is source for showing a list of commands for auto completion in vscode terminal, a similar file is mainatined in vscode repo.
jongio
reviewed
Aug 4, 2026
jongio
left a comment
jongio
left a comment
Member
There was a problem hiding this comment.
Re-reviewed at 8c10781. The hooks middleware revert is byte-identical to main, and locally go build ./... plus the middleware, usage, figspec, tool, and extension suites all pass.
That revert is the only change since my last pass, so the items you and @JeffreyCA settled on (JSON action / upgraded / dependencyUpgrades renames, ext.update and tool.update.* telemetry, --no-dependency-updates, Go identifier renames) are all still outstanding. Three things worth deciding before they land:
- The CHANGELOG entry needs a Breaking Changes split once the JSON keys move.
--no-dependency-updatesneeds explicit reconciliation with the old flag, or pflag will silently drop it.- The command span rename breaks telemetry continuity and there's no dashboard plan mentioned.
Details inline.
|
|
||
| ### Other Changes | ||
|
|
||
| - Rename the `azd extension upgrade` and `azd tool upgrade` commands to `azd extension update` and `azd tool update`. The former `upgrade` names continue to work as aliases for backward compatibility. |
Member
There was a problem hiding this comment.
You noted below that the JSON output is changing after all. Once that lands, this entry understates the impact: azd extension update -o json and azd tool update -o json change action, upgraded, and dependencyUpgrades, and those changes also hit callers who invoke the commands through the upgrade alias. So "continue to work as aliases for backward compatibility" won't be accurate for scripted consumers, which are exactly the ones the alias is meant to protect.
This repo already has a ### Breaking Changes convention (13 prior releases use it, and it sorts first within a release, see 1.28.0 and 1.23.15).
Suggested change
| - Rename the `azd extension upgrade` and `azd tool upgrade` commands to `azd extension update` and `azd tool update`. The former `upgrade` names continue to work as aliases for backward compatibility. | |
| - Rename the `azd extension upgrade` and `azd tool upgrade` commands to `azd extension update` and `azd tool update`. The former `upgrade` names continue to work as command aliases. |
Then add a ### Breaking Changes section above ### Other Changes covering the renamed JSON keys, and note they apply to the legacy upgrade aliases too.
| cmd.Flags().BoolVar(&flags.all, "all", false, "Update all installed extensions") | ||
| cmd.Flags().BoolVar(&flags.noDependencyUpgrades, "no-dependency-upgrades", false, | ||
| "Do not upgrade dependencies when upgrading an extension that has dependencies") | ||
| "Do not update dependencies when updating an extension that has dependencies") |
Member
There was a problem hiding this comment.
When you add --no-dependency-updates and keep this one as a hidden alias, watch out: pflag has no native flag aliasing. If you register a second BoolVar and MarkHidden or MarkDeprecated it, the two flags get separate backing fields, so a user passing --no-dependency-upgrades sets only the legacy field and any code reading the new field silently ignores it. The flag becomes a no-op, which is worse than removing it outright, since scripts keep passing it and dependencies get updated anyway.
Two ways out:
cmd.Flags().SetNormalizeFuncmappingno-dependency-upgradestono-dependency-updates. Single backing field, old name keeps parsing, only the new name shows in help.- Keep two fields and reconcile explicitly:
if cmd.Flags().Changed("no-dependency-upgrades") {
flags.noDependencyUpdates = flags.noDependencyUpgrades
}MarkDeprecated is already used at cli/azd/extensions/azure.ai.agents/internal/cmd/run.go:110 if you want the warning behavior, but it still needs the reconciliation in option 2. Whichever you pick, a test that passes the legacy flag and asserts dependencies are skipped would lock it down.
| | **Hooks** | `hooks.exec` | `hooks.name`, `hooks.type`, `hooks.kind` | Hook usage by type | | ||
| | **Container Build** | `container.publish`, `container.remotebuild`, `tools.pack.build` | `pack.builder.image` | Build method usage, success rates | | ||
| | **Tool Management (`azd tool`)** | `cmd.tool.install`, `cmd.tool.upgrade`, `cmd.tool.uninstall`, `cmd.tool.check` | `tool.id`, `tool.install.strategy` | Install/upgrade/uninstall success, upgrade availability | | ||
| | **Tool Management (`azd tool`)** | `cmd.tool.install`, `cmd.tool.update`, `cmd.tool.uninstall`, `cmd.tool.check` | `tool.id`, `tool.install.strategy` | Install/update/uninstall success, update availability | |
Member
There was a problem hiding this comment.
The span rename is the one piece of this with no compatibility shim at all. cmd.tool.upgrade becomes cmd.tool.update and cmd.extension.upgrade becomes cmd.extension.update even when the user types azd tool upgrade, because the span name is derived from the canonical command path and the alias resolves to it before the span is created.
If ext.upgrade and tool.upgrade.* also move to update per the discussion above, then every saved query and dashboard keyed on the old names goes quiet on release day, and any cross-version trend splits at the boundary rather than showing a real drop.
Is someone updating the dashboards as part of this, or should the old event names be dual-emitted for a release so the transition stays visible? Worth calling out in the PR description either way, since it's the kind of thing that gets noticed a week after release when a chart flatlines.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21cd8119-a644-4b3c-8c99-3f89f63a9968
Contributor
There was a problem hiding this comment.
Review details
Suppressed comments (7)
cli/azd/internal/tracing/events/events.go:32
- This changes the explicit telemetry contract from
ext.upgradetoext.update, even though the PR scope says explicit event keys remain unchanged. Unlike the intentionally auto-derivedcmd.extension.updatespan, this splits the lifecycle event into a new series and breaks existing dashboards and queries. Keep emitting the existingext.upgradeevent from the renamed command; only the command span name should change.
// ExtensionUpdateEvent tracks a single extension update attempt.
ExtensionUpdateEvent = "ext.update"
cli/azd/internal/tracing/fields/fields.go:1201
- The extension telemetry fields are also durable explicit keys. Replacing
extension.upgrade.*andextension.dependency_upgrade_countwith newupdatekeys splits historical metrics and contradicts the PR's non-goal of changing telemetry keys. Preserve the existing identifiers and key strings; only user-facing wording and the auto-derived command span should useupdate.
// ExtensionUpdateDurationMs is the time in milliseconds for one update.
ExtensionUpdateDurationMs = AttributeKey{
Key: attribute.Key("extension.update.duration_ms"),
cli/azd/cmd/tool.go:1362
- The
actionargument is serialized intotoolInstallResultItem.Action, so changing it toupdatebreaks the existing--output jsoncontract, including scripts that continue invoking the promisedupgradealias. Keep the machine-readable value stable asupgrade; if failure text must say “update,” pass a separate display verb instead of reusing the JSON value.
outcome := runToolOperation(ctx, toolsToUpgrade, operationFn, "Updating", "update", a.console,
cli/azd/cmd/tool.go:1537
- This value is emitted as the
actionfield by--dry-run --output json, so changing it fromupgradetoupdateis another machine-readable breaking change despite retaining the old command alias. Preserveupgradein JSON while usingupdateonly for the human-readable dry-run table.
action := "update"
cli/azd/internal/tracing/fields/fields.go:632
- These are explicit telemetry field keys, not command-path-derived names. Renaming them to
tool.update.*contradicts the stated compatibility scope and causes existingtool.upgrade.*dashboards and Kusto queries to stop receiving data. Keep the existingToolUpgrade*identifiers andtool.upgrade.*keys while allowing the command span itself to becomecmd.tool.update.
// ToolUpdateFromVersionKey records the previous version of a tool
// being updated (single-target updates only).
ToolUpdateFromVersionKey = AttributeKey{
Key: attribute.Key("tool.update.from_version"),
cli/azd/cmd/extension.go:2131
- This status description is telemetry, not user-facing text. Renaming it creates another incompatible value for downstream failure queries even though the PR is scoped to a command rename. Keep
upgrade.failedstable alongside the existing upgrade event and field keys.
span.SetStatus(codes.Error, "update.failed")
cli/azd/extensions/azure.coding-agent/README.md:29
- The introductory sentence still uses the old verb and is missing “have,” so it now contradicts the command directly below it. Update the sentence along with the example.
azd extension update azure.coding-agent
- Files reviewed: 49/49 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Contributor
Azure Dev CLI Install InstructionsInstall scriptsMacOS/Linux
bash: pwsh: WindowsPowerShell install MSI install Standalone Binary
MSI
Documentationlearn.microsoft.com documentationtitle: Azure Developer CLI reference
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The
upgradeverb was inconsistent with the rest of azd's user-facing vocabulary,where "update" is the common term for moving to a newer version. This renames the
two user-facing
upgradecommands toupdateso the CLI reads consistently.What changed
azd extension upgrade->azd extension updateandazd tool upgrade->azd tool update. The oldupgradenames still work ascobra aliases, so existing scripts and muscle memory keep working.
messages, done/summary headers, suggestions, and error strings from
"Upgrade/Upgrading/Upgraded" to "Update/Updating/Updated".
extension-framework.md,extension-resolution-and-versioning.md,creating-an-extension.md) to the newcommand names, noting the
upgradealias.*-upgrade.snaptestdatafiles to
*-update.snapand fixed affected test assertions.Scope / non-goals
To keep this a user-facing rename only, the following were intentionally left
unchanged:
UpgradeOptions,.Upgrade()).ext.upgrade,tool.upgrade.*) andchangelog history.
--no-dependency-upgradesflag name (a stable flag identifier).Note: the auto-derived telemetry command span name follows the command path, so it
shifts to
cmd.tool.update/cmd.extension.update. The explicit telemetry fieldkeys above are unchanged.