Rename azd extension/tool UPGRADE commands to UPDATE by hyoshis · Pull Request #9370 · Azure/azure-dev

hyoshis · 2026-07-30T18:36:49Z

Why

The upgrade verb 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 upgrade commands to update so the CLI reads consistently.

What changed

Renamed azd extension upgrade -> azd extension update and
azd tool upgrade -> azd tool update. The old upgrade names still work as
cobra aliases, so existing scripts and muscle memory keep working.
Updated all displayed help text, flag descriptions, prompts, spinner/progress
messages, done/summary headers, suggestions, and error strings from
"Upgrade/Upgrading/Upgraded" to "Update/Updating/Updated".
Updated user-facing docs (extension-framework.md,
extension-resolution-and-versioning.md, creating-an-extension.md) to the new
command names, noting the upgrade alias.
Regenerated usage and figspec snapshots; renamed the *-upgrade.snap testdata
files to *-update.snap and fixed affected test assertions.
Added a CHANGELOG entry under Unreleased.

Scope / non-goals

To keep this a user-facing rename only, the following were intentionally left
unchanged:

Go identifiers (types, functions, struct fields such as UpgradeOptions,
.Upgrade()).
Telemetry field/event key constants (ext.upgrade, tool.upgrade.*) and
changelog history.
The --no-dependency-upgrades flag 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 field
keys above are unchanged.

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

github-actions · 2026-07-30T18:37:16Z

🔗 Linked Issue Required

Thanks for the contribution! Please link a GitHub issue to this PR by adding Fixes #123 to the description or using the sidebar.
No issue yet? Feel free to create one!

azure-pipelines · 2026-07-30T18:37:27Z

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.

Copilot

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 update and tool update commands.
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 update changes the serialized action field in --dry-run --output json; the normal update path makes the same change at line 1362. Existing automation invoking the backward-compatible upgrade alias 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

 				{
-					name: ['upgrade'],
-					description: 'Upgrade installed extensions to the latest version.',
+					name: ['update', 'upgrade'],


+	// azd extension update <extension-id>
+	group.Add("update", &actions.ActionDescriptorOptions{
 		Command: &cobra.Command{
-			Use:   "upgrade [extension-id]",
-			Short: "Upgrade installed extensions to the latest version.",
-			Long: `Upgrade one or more installed extensions.
+			Use:     "update [extension-id]",
+			Aliases: []string{"upgrade"},


+	// azd tool update [tool-name...]
+	group.Add("update", &actions.ActionDescriptorOptions{
 		Command: &cobra.Command{
-			Use:   "upgrade [tool-name...]",
-			Short: "Upgrade installed tools.",
+			Use:     "update [tool-name...]",
+			Aliases: []string{"upgrade"},


+| Status text         | Meaning                       | Color helper        |
+| ------------------- | ----------------------------- | ------------------- |
+| `Installed` / `Up to date` | Present and current      | `WithSuccessFormat` |
+| `Upgrade available` | Installed but outdated        | `WithWarningFormat` |


+Nightly versions use semver prerelease labels, so the standard `azd extension update` flow works:

- A newer nightly (higher build id, or a higher base version) supersedes an older one, so `azd extension upgrade` pulls the latest nightly.
+- A newer nightly (higher build id, or a higher base version) supersedes an older one, so `azd extension update` pulls the latest nightly.


+# Azure Developer CLI (`azd`) Agentic UX Style Guide
+
+## Overview
+
+This guide covers the **agentic (AI / GitHub Copilot) UX patterns** for the Azure Developer CLI. These are a **deliberately distinct visual system** from the core azd flows documented in [azd-style-guide.md](./azd-style-guide.md).


hyoshis and others added 3 commits July 30, 2026 11:21

docs: clarify agentic experience entry point

021a845

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: be625a8a-0787-45ea-b3d9-a782d4c2651f

hyoshis requested a review from kristenwomack July 30, 2026 18:36

hyoshis self-assigned this Jul 30, 2026

Copilot AI review requested due to automatic review settings July 30, 2026 18:36

hyoshis requested review from JeffreyCA, RickWinter, hemarina, richardpark-msft, tg-msft and vhvb1989 as code owners July 30, 2026 18:36

Copilot started reviewing on behalf of hyoshis July 30, 2026 18:37 View session

github-actions Bot added the area/extensions Extensions (general) label Jul 30, 2026

Copilot AI reviewed Jul 30, 2026

View reviewed changes

hyoshis linked an issue Jul 30, 2026 that may be closed by this pull request

[Extension] Rename upgrade to update #7262

Open

3 tasks

vhvb1989 approved these changes Jul 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Rename azd extension/tool UPGRADE commands to UPDATE - #9370

Rename azd extension/tool UPGRADE commands to UPDATE#9370
hyoshis wants to merge 3 commits into
mainfrom
hyoshis-rename-upgrade-to-update

hyoshis commented Jul 30, 2026

Uh oh!

github-actions Bot commented Jul 30, 2026

Uh oh!

azure-pipelines Bot commented Jul 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

hyoshis commented Jul 30, 2026

Why

What changed

Scope / non-goals

Uh oh!

github-actions Bot commented Jul 30, 2026

🔗 Linked Issue Required

Uh oh!

azure-pipelines Bot commented Jul 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants