Skip to content

[docs] Update documentation for features from 2026-04-05 #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[docs] Update documentation for features from 2026-04-05 #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 9 additions & 14 deletions cli/azd/docs/design/azd-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Today, when a new version of `azd` is available, users see a warning message wit
2. **Auto-update** — opt-in background updates applied at next startup
3. **Channel management** — ability to switch between `stable` and `daily` builds

The feature ships as a hidden command behind an alpha feature toggle (`alpha.update`) for safe rollout. When the toggle is off, there are zero changes to existing behavior — `azd version`, update notifications, everything stays exactly as it is today.
The feature ships as a command currently in Beta. On first use, a notice is displayed. The `azd update` command is always available.

---

Expand All @@ -24,7 +24,7 @@ The feature ships as a hidden command behind an alpha feature toggle (`alpha.upd
- Preserve user control (opt-out, channel selection, check interval)
- Avoid disruption to CI/CD pipelines
- Respect platform install methods (Homebrew, winget, choco, scripts)
- Ship safely behind a feature flag with zero impact when off
- Ship safely as a beta feature while gathering feedback

---

Expand Down Expand Up @@ -122,8 +122,6 @@ azd config set updates.autoUpdate on # or "off" (default: off)

Channel is set via `azd update --channel <stable|daily>` (which persists the choice to `updates.channel` config). Default channel is `stable`.

These follow the existing convention of `"on"/"off"` for boolean-like config values (consistent with alpha features).

### 2. Daily Build Version Tracking

**Problem**: Daily builds share a base semver (e.g., `1.24.0-beta.1`), so version comparison alone can't tell if a newer daily exists.
Expand Down Expand Up @@ -239,8 +237,6 @@ Most install methods write to system directories requiring elevation:

**Auto-update is off by default.** Background downloading and staged apply only happen when the user explicitly opts in via `azd config set updates.autoUpdate on` or `azd update --auto-update on`. Without opt-in, the only background activity is the existing version check (cheap HTTP GET) that shows a banner — no downloads occur.

Additionally, auto-update is gated behind the `update` alpha feature flag during the rollout phase.

When `updates.autoUpdate` is set to `on`:

**Cache TTL** (channel-dependent):
Expand Down Expand Up @@ -327,8 +323,6 @@ azd version 1.24.0-beta.1-daily.5935787 (commit abc1234) (daily)

The channel suffix is derived from the running binary's version string (presence of `daily.` pattern), not the configured channel. This means the output always reflects what the binary actually is.

When the feature toggle is off, `azd version` output stays unchanged — no suffix, no channel info.

### 7. Telemetry

Uses the existing azd telemetry infrastructure (OpenTelemetry). New telemetry fields tracked on every update operation:
Expand Down Expand Up @@ -358,17 +352,18 @@ Uses the existing azd telemetry infrastructure (OpenTelemetry). New telemetry fi
| `update.unsupportedInstallMethod` | Unknown or unsupported install method |
| `update.channelSwitchDowngrade` | User declined when switching channels |
| `update.skippedCI` | Skipped due to CI/non-interactive environment |
| `update.nonStandardInstall` | Non-standard install location detected |
| `update.configFailed` | Failed to read or persist user config |
| `update.invalidInput` | Invalid flag value (e.g., unrecognized channel) |

These codes are integrated into azd's `MapError` pipeline, so update failures show up properly in telemetry dashboards alongside other command errors.

### 8. Feature Toggle (Alpha Gate)

The entire update feature ships behind `alpha.update` (default: off). This means:
### 8. Feature Stage (Beta)

- **Toggle off** (default): Zero behavior changes. `azd version` output is the same. Update notification shows the existing platform-specific install instructions. `azd update` returns an error telling the user to enable the feature.
- **Toggle on** (`azd config set alpha.update on`): All update features are active — `azd update` works, auto-update stages/applies, `azd version` shows the channel suffix, notifications say "run `azd update`."
The update command is listed as **Beta** in [`feature-stages.md`](../feature-stages.md).

This lets us roll out to internal users first, gather feedback, and fix issues before broader availability. Once stable, the toggle can be removed and the feature enabled by default.
- `azd update` works without needing any config toggle.
- On first use, when no `updates.*` configuration exists, a notice is displayed and a default channel is persisted so the notice only appears once.

### 9. Update Banner Suppression

Expand Down
1 change: 1 addition & 0 deletions cli/azd/docs/feature-stages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ As of `1.21.1`, each Azure Developer CLI feature has been evaluated and assigned
| Command | package | Beta |
| Command | add | Beta |
| Command | infra generate | Beta |
| Command | update | Beta |
| Language | Python | Stable |
| Language | JavaScript/TypeScript | Stable |
| Language | Java | Stable |
Expand Down