diff --git a/cli/azd/docs/extensions/extension-framework.md b/cli/azd/docs/extensions/extension-framework.md index 38a12a7836a..39bd88b1095 100644 --- a/cli/azd/docs/extensions/extension-framework.md +++ b/cli/azd/docs/extensions/extension-framework.md @@ -66,13 +66,13 @@ azd extension source add -n azd -t url -l "https://aka.ms/azd/extensions/registr > **Note:** When the `registry.json` file is modified, CI automatically runs snapshot tests to ensure extension commands are properly documented in CLI help output and VS Code IntelliSense. See [Snapshot Testing for Extensions](#snapshot-testing-for-extensions) for details. -#### Development Registry +#### Dev (Experimental) Registry > [!CAUTION] -> Extensions hosted in the dev registry DO NOT contain signed binaries at the moment. +> Extensions hosted in the dev registry are unsigned. They come with **no stability guarantees** and are **not covered by Azure support**. Expect breaking changes, rough edges, and possible removal without notice. A shared development registry can be added to your `azd` configuration. -This registry contains extensions that are experiments and also used for internal testing before shipping official extensions. +This registry contains experimental extensions, community contributions not yet vetted, pre-release builds, and extensions used for internal testing before shipping to the official registry. The registry is hosted in the [`azd` GitHub repo](https://github.com/Azure/azure-dev/blob/main/cli/azd/extensions/registry.dev.json). To opt-in for the development registry run the following command: @@ -82,6 +82,8 @@ To opt-in for the development registry run the following command: azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev" ``` +Extensions installed from the dev registry are automatically promoted to the main registry when a newer version becomes available there. See the [Dev/Experimental Extension Registry](./extension-resolution-and-versioning.md#devexperimental-extension-registry) section for full details on stability expectations, submission guidelines, promotion behavior, and troubleshooting. + #### `azd extension source list` Displays a list of installed extension sources. @@ -603,7 +605,7 @@ The easiest way to get started building extensions is to install the `azd` Devel > [!IMPORTANT] > Ensure you have added the `dev` extension source to your `azd` configuration > -> [Configure dev extension source](#development-registry) +> [Configure dev extension source](#dev-experimental-registry) ```bash # Install the `azd` developer extension diff --git a/cli/azd/docs/extensions/extension-resolution-and-versioning.md b/cli/azd/docs/extensions/extension-resolution-and-versioning.md index c9d30dad652..79120cec210 100644 --- a/cli/azd/docs/extensions/extension-resolution-and-versioning.md +++ b/cli/azd/docs/extensions/extension-resolution-and-versioning.md @@ -305,6 +305,248 @@ When `latest` is specified (or the version is omitted), `azd` selects the **high azd extension install --source ``` +## Dev/Experimental Extension Registry + +The dev (experimental) registry is a separate extension source for bleeding-edge, pre-release, and community-contributed extensions that have not yet been promoted to the official `azd` registry. It lives alongside the main registry in the `azure-dev` repository and is served via a dedicated aka.ms link. While `azd` and `dev` are the official source names, the extension source system supports adding custom sources with any name via `azd extension source add`. + +| Property | Main Registry | Dev Registry | +|----------|---------------|--------------| +| URL | `https://aka.ms/azd/extensions/registry` | `https://aka.ms/azd/extensions/registry/dev` | +| Source file | `cli/azd/extensions/registry.json` | `cli/azd/extensions/registry.dev.json` | +| Source name | `azd` (built-in default) | `dev` (official dev registry) | +| Signed binaries | Yes | **No** | +| Support | Covered by Azure support | **Not covered** | + +### Experimental vs. Main Registry Criteria + +The following criteria determine whether an extension belongs in the dev registry or the main registry: + +| Criteria | Main (azd) | Experimental (dev) | +|----------|------------|-------------------| +| **Binary signing** | Signed builds | Unsigned builds | +| **Stability** | Stable releases | Preview, alpha, beta, or pre-release versions | +| **Vetting** | Vetted by the azd team; meets quality bar | Community contributions not yet reviewed; internal experiments | +| **API surface** | Follows [semver guidance](#semantic-versioning-guidance) | May change between versions without notice | +| **Availability** | Maintained with deprecation process | May be removed without notice | + +An extension can exist in **both** registries simultaneously. For example, the main registry may contain version `1.2.0` while the dev registry contains `2.0.0-beta.1`. This allows authors to publish stable releases through the main registry while testing upcoming versions through the dev registry. + +### Stability Expectations + +> [!CAUTION] +> Extensions in the dev registry come with **no stability guarantees**. + +When using experimental extensions, expect: + +- **Breaking changes** between versions without prior notice +- **Removal** of extensions from the registry without deprecation +- **No Azure support** — experimental extensions are not covered by any Azure support plan +- **Unsigned binaries** — your system may show security warnings when running them +- **Rough edges** — incomplete documentation, missing error messages, and untested edge cases + +The dev registry is intended for early adopters, extension authors testing pre-release builds, and internal teams validating extensions before official publication. + +### Adding the Dev Registry + +The dev registry is **not** configured by default. To opt in: + +```bash +# Add the dev registry as a source named "dev" +azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev" +``` + +Verify it was added: + +```bash +azd extension source list +``` + +You should see both `azd` (the built-in default) and `dev` listed. + +To remove the dev registry later: + +```bash +azd extension source remove dev +``` + +### Installing Experimental Extensions + +Once the dev source is configured, you can browse and install experimental extensions: + +```bash +# List all available extensions (from all configured sources) +azd extension list --available + +# Install an extension from the dev registry explicitly +azd extension install my.experimental.extension --source dev + +# Install a specific pre-release version +azd extension install my.experimental.extension --version 2.0.0-beta.1 --source dev +``` + +If an extension exists in both the `azd` and `dev` sources and you do not specify `--source`, `azd` will prompt you to choose (in interactive mode) or return an error (in non-interactive mode). See [Handle Conflicts](#3-handle-conflicts) for details. + +### Upgrade and Dev→Main Promotion + +When you run `azd extension upgrade`, extensions installed from the dev registry are evaluated for **one-way promotion** to the main registry. Promotion occurs automatically when: + +1. **The extension is no longer in the dev registry** — it was removed from `registry.dev.json` after being promoted to `registry.json`. +2. **The main registry has a newer version** — the latest version in the main registry is strictly greater than the latest version in the dev registry. + +When promotion happens, the extension's stored source switches from `dev` to `azd`. This is a one-way operation — extensions are never demoted from the main registry back to the dev registry. + +> [!NOTE] +> If the main and dev registries have the **same** latest version, the extension stays on its current (dev) source. Equal versions are source-sticky. + +The upgrade priority chain is: + +1. **Explicit `--source` flag** — always wins if provided +2. **Stored source** — the source the extension was originally installed from +3. **Main registry fallback** — `azd` checks the main registry for promotion opportunities + +Promotion events are tracked via `ext.promote` telemetry. Upgrade events (regardless of promotion) are tracked via `ext.upgrade`. + +#### Example: Dev→Main Promotion in Action + +```bash +# Install from dev registry +azd extension install my.extension --source dev + +# Later, the extension graduates to the main registry with a newer version. +# Running upgrade will auto-promote: +azd extension upgrade my.extension +# Output: my.extension upgraded from 1.0.0-beta.2 (dev) → 1.0.0 (azd) +``` + +### Submitting an Extension to the Dev Registry + +To publish an extension to the dev registry, submit a pull request to the [azure-dev](https://github.com/Azure/azure-dev) repository that adds your extension entry to `cli/azd/extensions/registry.dev.json`. + +#### Requirements + +Your extension entry must: + +1. **Pass schema validation** — The entry must conform to the [registry schema](https://github.com/Azure/azure-dev/blob/main/cli/azd/extensions/registry.schema.json). CI validates this automatically via `ext-registry-ci.yml`. +2. **Include all required metadata:** + - `id` — Unique identifier (lowercase, alphanumeric, dots, and hyphens: `^[a-z0-9-.]+$`) + - `namespace` — Classification namespace + - `displayName` — Human-readable name + - `description` — Brief description of the extension's purpose + - `versions` — At least one version entry with `version`, `capabilities`, `usage`, `examples`, and `artifacts` +3. **Include checksums for all artifacts** — Each artifact must declare a `checksum` with an `algorithm` (`sha256` or `sha512`) and `value`. +4. **Provide platform artifacts** — At minimum, include artifacts for `linux/amd64`, `darwin/amd64`, `darwin/arm64`, and `windows/amd64`. + +#### Example Entry + +```json +{ + "id": "my.experimental.extension", + "namespace": "my", + "displayName": "My Experimental Extension", + "description": "An experimental extension for testing new features.", + "versions": [ + { + "version": "0.1.0", + "capabilities": ["custom-commands"], + "usage": "azd my-command [options]", + "examples": [ + { + "name": "basic-usage", + "description": "Run my-command with a flag.", + "usage": "azd my-command --flag value" + } + ], + "artifacts": { + "linux/amd64": { + "url": "https://github.com/my-org/my-ext/releases/download/v0.1.0/my-ext-linux-amd64.tar.gz", + "checksum": { + "algorithm": "sha256", + "value": "abc123..." + } + }, + "darwin/amd64": { + "url": "https://github.com/my-org/my-ext/releases/download/v0.1.0/my-ext-darwin-amd64.tar.gz", + "checksum": { + "algorithm": "sha256", + "value": "bcd234..." + } + }, + "darwin/arm64": { + "url": "https://github.com/my-org/my-ext/releases/download/v0.1.0/my-ext-darwin-arm64.tar.gz", + "checksum": { + "algorithm": "sha256", + "value": "def456..." + } + }, + "windows/amd64": { + "url": "https://github.com/my-org/my-ext/releases/download/v0.1.0/my-ext-windows-amd64.zip", + "checksum": { + "algorithm": "sha256", + "value": "789ghi..." + } + } + } + } + ] +} +``` + +#### Review Process + +- A maintainer will review your PR for schema compliance, metadata completeness, and artifact accessibility. +- There is no formal quality gate for the dev registry — it is intentionally lower-friction than the main registry. +- Extensions that mature and meet the [main registry criteria](#experimental-vs-main-registry-criteria) can be promoted via a separate PR to `registry.json`. + +### Troubleshooting Multi-Registry Scenarios + +#### Extension exists in both registries + +When the same extension ID is present in both `azd` and `dev`: + +- **Interactive mode** — `azd` prompts you to choose which source to install from. +- **Non-interactive mode** — `azd` fails with `"found in multiple sources"`. +- **Resolution** — Use `--source` to specify explicitly: + + ```bash + azd extension install my.extension --source dev + azd extension install my.extension --source azd + ``` + +#### Source ordering affects resolution + +Sources are sorted **alphabetically by name**. With the default naming (`azd` and `dev`), `azd` is consulted first because `"azd"` sorts before `"dev"`. If you name your dev source `"aaa-dev"`, it would be consulted first. The name only affects the order in which sources are searched — it does not affect upgrade or promotion behavior. + +#### Stale cache after registry updates + +If a recently published extension does not appear, the local cache may not have expired yet: + +```bash +# Force a fresh fetch by setting TTL to zero +export AZD_EXTENSION_CACHE_TTL=0s # Linux/macOS +$env:AZD_EXTENSION_CACHE_TTL = "0s" # PowerShell + +# Then retry +azd extension list --available +``` + +Or clear the cache manually: + +```bash +# Linux/macOS +rm -rf ~/.azd/cache/extensions/ + +# PowerShell +Remove-Item -Recurse -Force "$env:USERPROFILE\.azd\cache\extensions\" +``` + +#### Unreachable dev source blocks all operations + +If the dev registry URL is unreachable (network issue, DNS failure), operations that load sources will **fail** rather than skip the unreachable source. To unblock yourself, remove the dev source temporarily: + +```bash +azd extension source remove dev +``` + ## Related Documentation | Document | Description | diff --git a/docs/architecture/extension-framework.md b/docs/architecture/extension-framework.md index 4e60d671d1e..8845e5bec64 100644 --- a/docs/architecture/extension-framework.md +++ b/docs/architecture/extension-framework.md @@ -23,10 +23,12 @@ azd (host) Extensions are discovered from registries — JSON manifests that list available extensions with their versions, capabilities, and download URLs. -- **Official registry:** `https://aka.ms/azd/extensions/registry` -- **Dev registry:** `https://aka.ms/azd/extensions/registry/dev` (unsigned builds, backed by `cli/azd/extensions/registry.dev.json`) +- **Official registry:** `https://aka.ms/azd/extensions/registry` — Stable, signed, production-ready extensions vetted by the azd team. +- **Dev registry:** `https://aka.ms/azd/extensions/registry/dev` — Experimental and pre-release extensions (unsigned builds, backed by `cli/azd/extensions/registry.dev.json`). Not configured by default; users opt in with `azd extension source add`. - **Local sources:** File-based manifests for development +The dev registry serves as a staging area for extensions before they graduate to the main registry. Extensions installed from the dev registry are automatically promoted to the main registry when a newer stable version becomes available there. See the [Extension Resolution and Versioning](../../cli/azd/docs/extensions/extension-resolution-and-versioning.md#devexperimental-extension-registry) guide for detailed criteria, stability expectations, and submission guidelines. + ### Lifecycle 1. User installs an extension: `azd extension install ` diff --git a/docs/guides/creating-an-extension.md b/docs/guides/creating-an-extension.md index 411c232e25c..7208ab124b5 100644 --- a/docs/guides/creating-an-extension.md +++ b/docs/guides/creating-an-extension.md @@ -58,9 +58,27 @@ azd x build go build ``` -### 5. Register in the extension registry +### 5. Register in the Main Extension Registry -For first-party extensions, add an entry to `cli/azd/extensions/registry.json` with version, capabilities, and download URLs. +When your extension is stable and ready for production use, add an entry to `cli/azd/extensions/registry.json` with version, capabilities, and download URLs. + +### 6. Publish to the Dev Registry First (Recommended) + +For extensions that are still in development or preview, consider publishing to the **dev (experimental) registry** first to gather feedback before graduating to the main registry: + +1. Add your extension entry to `cli/azd/extensions/registry.dev.json` in a PR to the [azure-dev](https://github.com/Azure/azure-dev) repository. +2. Your entry must pass schema validation (CI checks this automatically) and include all required metadata — `id`, `namespace`, `displayName`, `versions` with artifacts and SHA256/SHA512 checksums. +3. Users can then install your extension by adding the dev source and installing from it: + + ```bash + azd extension source add -n dev -t url -l "https://aka.ms/azd/extensions/registry/dev" + azd extension install my.extension --source dev + ``` + +4. Once your extension is stable and meets the quality bar, submit a follow-up PR to add it to `cli/azd/extensions/registry.json`. Users who installed from the dev registry will be **automatically promoted** to the main registry on their next `azd extension upgrade`. + +> [!NOTE] +> Extensions in the dev registry have no stability guarantees, are unsigned, and are not covered by Azure support. This is expected and appropriate for pre-release testing. See the [Dev/Experimental Extension Registry](../../cli/azd/docs/extensions/extension-resolution-and-versioning.md#devexperimental-extension-registry) guide for full details. ## Extension Design Guidelines