From 322fe350de3307353f1e4da7065aeab77fa6ff7e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 14:05:19 +0000 Subject: [PATCH 1/5] Initial plan From 9d53a9922d659284347e8a1b83f6a29de110f8a8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 14:27:25 +0000 Subject: [PATCH 2/5] Add structured docs/ directory, copilot instructions, and update README Create docs/ at repo root with concepts/, guides/, reference/, and architecture/ subdirectories. Add initial documentation covering: - Glossary, feature stages, alpha features (concepts) - Contributing, adding commands, creating extensions, observability (guides) - Environment variables, azure.yaml schema, feature status (reference) - System overview, command execution, extension framework, provisioning (architecture) - ADR template for future architecture decision records Add .github/instructions/documentation.instructions.md with copilot instructions to keep docs up to date when codebase changes. Update root README.md to link to the new docs/ directory. Co-authored-by: spboyer <7681382+spboyer@users.noreply.github.com> --- .../documentation.instructions.md | 44 +++++++ README.md | 2 +- docs/README.md | 63 ++++++++++ docs/architecture/adr-template.md | 35 ++++++ docs/architecture/command-execution-model.md | 84 +++++++++++++ docs/architecture/extension-framework.md | 92 +++++++++++++++ docs/architecture/provisioning-pipeline.md | 75 ++++++++++++ docs/architecture/system-overview.md | 95 +++++++++++++++ docs/concepts/alpha-features.md | 51 ++++++++ docs/concepts/feature-stages.md | 39 ++++++ docs/concepts/glossary.md | 111 ++++++++++++++++++ docs/guides/adding-a-new-command.md | 98 ++++++++++++++++ docs/guides/contributing.md | 94 +++++++++++++++ docs/guides/creating-an-extension.md | 78 ++++++++++++ docs/guides/observability.md | 80 +++++++++++++ docs/reference/azure-yaml-schema.md | 69 +++++++++++ docs/reference/environment-variables.md | 53 +++++++++ docs/reference/feature-status.md | 76 ++++++++++++ 18 files changed, 1238 insertions(+), 1 deletion(-) create mode 100644 .github/instructions/documentation.instructions.md create mode 100644 docs/README.md create mode 100644 docs/architecture/adr-template.md create mode 100644 docs/architecture/command-execution-model.md create mode 100644 docs/architecture/extension-framework.md create mode 100644 docs/architecture/provisioning-pipeline.md create mode 100644 docs/architecture/system-overview.md create mode 100644 docs/concepts/alpha-features.md create mode 100644 docs/concepts/feature-stages.md create mode 100644 docs/concepts/glossary.md create mode 100644 docs/guides/adding-a-new-command.md create mode 100644 docs/guides/contributing.md create mode 100644 docs/guides/creating-an-extension.md create mode 100644 docs/guides/observability.md create mode 100644 docs/reference/azure-yaml-schema.md create mode 100644 docs/reference/environment-variables.md create mode 100644 docs/reference/feature-status.md diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md new file mode 100644 index 00000000000..3f4e44dd8fd --- /dev/null +++ b/.github/instructions/documentation.instructions.md @@ -0,0 +1,44 @@ +# Documentation Maintenance + +This repository uses a structured documentation system under `docs/` at the repo root. +When making changes to the codebase, keep the documentation current. + +## Documentation Structure + +```text +docs/ +├── README.md — Documentation index and navigation +├── concepts/ — Core mental models, terminology, feature lifecycle +├── guides/ — Task-oriented how-tos for contributors +├── reference/ — Schemas, flags, environment variables, feature status +└── architecture/ — System overviews, design context, ADRs +``` + +## When to Update Documentation + +- **New command or flag:** Update `docs/guides/adding-a-new-command.md` if the pattern changes; update `docs/reference/feature-status.md` with the new feature's stage. +- **New environment variable:** Add it to `docs/reference/environment-variables.md`. +- **New extension capability:** Update `docs/architecture/extension-framework.md` and `docs/guides/creating-an-extension.md`. +- **Feature stage change:** Update `docs/reference/feature-status.md` when a feature graduates (alpha → beta → stable). +- **New concept or term:** Add it to `docs/concepts/glossary.md`. +- **Architecture decision:** Create a new ADR using the template at `docs/architecture/adr-template.md`. +- **New hosting target or language:** Update `docs/reference/feature-status.md` and `docs/concepts/glossary.md`. + +## Documentation Placement Guide + +| Content type | Location | +|---|---| +| Term or concept definition | `docs/concepts/glossary.md` | +| Contributor how-to | `docs/guides/` | +| Configuration reference | `docs/reference/` | +| System design or ADR | `docs/architecture/` | +| Implementation design details | `cli/azd/docs/design/` | +| Extension development details | `cli/azd/docs/extensions/` | +| Code style standards | `cli/azd/docs/style-guidelines/` | + +## Documentation Standards + +- Use clear, concise language +- Link to detailed implementation docs in `cli/azd/docs/` rather than duplicating content +- Keep tables and lists scannable +- Include code examples where they aid understanding diff --git a/README.md b/README.md index 0afb9d672aa..21d12710450 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ ## 🤖 AI Agents -**Contributing to this repo?** See [AGENTS.md](cli/azd/AGENTS.md) for coding standards and guidelines. +**Contributing to this repo?** See [AGENTS.md](cli/azd/AGENTS.md) for coding standards and [docs/](docs/README.md) for contributor documentation. **Using `azd` with an AI coding assistant?** Check out the [docs](https://aka.ms/azd) and [templates](https://azure.github.io/awesome-azd/). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..b67477dd0fd --- /dev/null +++ b/docs/README.md @@ -0,0 +1,63 @@ +# Azure Developer CLI Documentation + +> Internal documentation for contributors and AI coding agents working on the Azure Developer CLI (`azd`). + +For end-user documentation, see [aka.ms/azd](https://aka.ms/azd). For template examples, see [awesome-azd](https://azure.github.io/awesome-azd/). + +--- + +## Concepts + +Core mental models, terminology, and feature lifecycle. + +- [Glossary](concepts/glossary.md) — Key terms and concepts used throughout the codebase +- [Feature Stages](concepts/feature-stages.md) — How features graduate from alpha → beta → stable +- [Alpha Features](concepts/alpha-features.md) — How experimental features are gated and discovered + +## Guides + +Task-oriented how-tos for common contributor workflows. + +- [Contributing](guides/contributing.md) — How to build, test, lint, and submit changes +- [Adding a New Command](guides/adding-a-new-command.md) — End-to-end walkthrough for new CLI commands +- [Creating an Extension](guides/creating-an-extension.md) — How to build and publish an azd extension +- [Observability and Tracing](guides/observability.md) — Adding telemetry, traces, and debugging + +## Reference + +Schemas, flags, environment variables, and configuration details. + +- [Environment Variables](reference/environment-variables.md) — All environment variables that configure azd behavior +- [azure.yaml Schema](reference/azure-yaml-schema.md) — Project configuration file reference +- [Feature Status](reference/feature-status.md) — Current maturity status of all features + +## Architecture + +System overviews, design context, and decision records. + +- [System Overview](architecture/system-overview.md) — High-level architecture and code organization +- [Command Execution Model](architecture/command-execution-model.md) — How commands are registered, resolved, and run +- [Extension Framework](architecture/extension-framework.md) — gRPC-based extension system architecture +- [Provisioning Pipeline](architecture/provisioning-pipeline.md) — How infrastructure provisioning works +- [ADR Template](architecture/adr-template.md) — Template for lightweight architecture decision records + +--- + +## Where do new docs go? + +| You want to document… | Put it in… | +|---|---| +| A new term or concept | `docs/concepts/glossary.md` | +| A how-to for contributors | `docs/guides/` | +| A configuration reference | `docs/reference/` | +| A system design or ADR | `docs/architecture/` | +| Detailed implementation design | `cli/azd/docs/design/` | +| Extension development details | `cli/azd/docs/extensions/` | +| Style and coding standards | `cli/azd/docs/style-guidelines/` | + +## Related documentation + +- [AGENTS.md](../AGENTS.md) — AI agent coding instructions +- [cli/azd/docs/](../cli/azd/docs/) — Detailed implementation-level documentation +- [cli/azd/docs/style-guidelines/](../cli/azd/docs/style-guidelines/) — Code style guide +- [cli/azd/docs/extensions/](../cli/azd/docs/extensions/) — Extension framework details diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md new file mode 100644 index 00000000000..5dcfb0a2dac --- /dev/null +++ b/docs/architecture/adr-template.md @@ -0,0 +1,35 @@ +# ADR Template + +Use this template to record lightweight architecture decisions. ADRs document the context, decision, and consequences of significant technical choices. + +## How to Use + +1. Copy this template to a new file: `docs/architecture/adr-NNN-title.md` +2. Fill in each section +3. Submit as part of the PR that implements the decision + +ADRs are immutable once accepted. If a decision is superseded, create a new ADR that references the original. + +--- + +## ADR-NNN: [Title] + +**Status:** Proposed | Accepted | Superseded by [ADR-NNN] + +**Date:** YYYY-MM-DD + +### Context + +What is the issue that we're seeing that is motivating this decision or change? + +### Decision + +What is the change that we're proposing and/or doing? + +### Consequences + +What becomes easier or more difficult to do because of this change? + +### Alternatives Considered + +What other approaches were evaluated, and why were they not chosen? diff --git a/docs/architecture/command-execution-model.md b/docs/architecture/command-execution-model.md new file mode 100644 index 00000000000..69da6e044c7 --- /dev/null +++ b/docs/architecture/command-execution-model.md @@ -0,0 +1,84 @@ +# Command Execution Model + +How CLI commands are registered, resolved, and executed in azd. + +## Pipeline Overview + +```text +ActionDescriptor → CobraBuilder → Cobra Command → Middleware → Action.Run() +``` + +### 1. ActionDescriptor Registration + +Commands are declared in `cmd/root.go` as a tree of ActionDescriptors: + +```go +root := actions.NewActionDescriptor("azd", nil) + +root.Add("up", &actions.ActionDescriptorOptions{ + Command: newUpCmd(), + ActionResolver: newUpAction, + FlagsResolver: newUpFlags, + OutputFormats: []actions.OutputFormat{actions.OutputFormatJson}, +}) +``` + +Each descriptor specifies: + +- **Command** — Cobra command metadata (name, description, examples) +- **ActionResolver** — Factory function to create the action via IoC +- **FlagsResolver** — Factory function to create the flags struct +- **OutputFormats** — Supported output formats (JSON, table, none) + +### 2. CobraBuilder + +At startup, the CobraBuilder walks the ActionDescriptor tree and generates standard Cobra commands. This decouples command definition from Cobra's API. + +### 3. Middleware Pipeline + +Before an action runs, the middleware chain processes cross-cutting concerns: + +| Middleware | Purpose | +|---|---| +| Telemetry | Creates root span, records command events and attributes | +| Hooks | Executes pre/post lifecycle hooks from `azure.yaml` | +| Extensions | Routes events to registered extensions | +| Debug | Handles `--debug` flag behavior | + +Middleware is registered in `cmd/middleware/` and composed as a chain around the action. + +### 4. Action Execution + +Actions implement the `actions.Action` interface: + +```go +type Action interface { + Run(ctx context.Context) (*ActionResult, error) +} +``` + +Actions receive dependencies via constructor injection through the IoC container. They return an `ActionResult` with a message and optional structured data for output formatting. + +### 5. Output Formatting + +When a command supports `--output`, the framework formats the `ActionResult`: + +- **JSON** — Serializes the result data as JSON +- **Table** — Renders the result data as a formatted table +- **None** — Displays only the result message + +## Error Handling + +- Actions return errors wrapped with `fmt.Errorf("context: %w", err)` +- `internal.ErrorWithSuggestion` adds user-facing fix suggestions +- The middleware pipeline catches and formats errors for display +- Context cancellations are handled gracefully + +## Adding a New Command + +See [Adding a New Command](../guides/adding-a-new-command.md) for a step-by-step guide. + +## Detailed Reference + +- [cli/azd/docs/style-guidelines/new-azd-command.md](../../cli/azd/docs/style-guidelines/new-azd-command.md) — Full implementation reference +- [Guiding Principles](../../cli/azd/docs/style-guidelines/guiding-principles.md) — Command design philosophy diff --git a/docs/architecture/extension-framework.md b/docs/architecture/extension-framework.md new file mode 100644 index 00000000000..8ff76aec72c --- /dev/null +++ b/docs/architecture/extension-framework.md @@ -0,0 +1,92 @@ +# Extension Framework + +Architecture of the gRPC-based extension system in azd. + +## Overview + +Extensions are external processes that communicate with azd via gRPC. They allow third parties and first-party teams to add new capabilities — languages, hosting targets, event handlers, and more — without modifying the core CLI. + +## Architecture + +```text +azd (host) + ├── Extension Registry (discovery) + ├── Extension Manager (lifecycle) + └── gRPC Broker (communication) + ↕ gRPC + Extension Process + ├── Capability Handlers + └── Service Implementations +``` + +### Discovery + +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) +- **Local sources:** File-based manifests for development + +### Lifecycle + +1. User installs an extension: `azd extension install ` +2. Extension binary is downloaded and cached locally +3. When needed, azd spawns the extension process +4. gRPC connection is established via the broker +5. azd invokes capability methods on the extension +6. Extension responds via gRPC + +### Communication + +The gRPC broker (`pkg/grpcbroker`) manages bidirectional communication. Extensions can both: + +- **Receive calls** from azd (e.g., "build this service") +- **Make calls** back to azd (e.g., "prompt the user", "read environment config") + +## Capabilities + +Extensions declare their capabilities in `extension.yaml`: + +| Capability | Description | +|---|---| +| `event-handler` | React to lifecycle events (pre/post provision, deploy, etc.) | +| `framework-service-provider` | Add build/restore support for new languages | +| `service-target-provider` | Add deployment support for new hosting targets | +| `compose-provider` | Custom orchestration logic | +| `workflow-provider` | Custom workflow steps | + +## Available gRPC Services + +Extensions can access these azd services via gRPC: + +- **Project** — Read project configuration +- **Environment** — Read/write environment values and secrets +- **User Config** — Read user-level azd configuration +- **Deployment** — Access deployment information +- **Account** — Access Azure account details +- **Prompt** — Display prompts and collect user input +- **AI Model** — Query AI model availability and quotas +- **Event** — Subscribe to and emit events +- **Container** — Container registry operations +- **Framework** — Framework service operations +- **Service Target** — Deployment target operations + +## Error Handling + +Extensions use two structured error types: + +- **`ServiceError`** — For Azure API or remote service errors +- **`LocalError`** — For client-side validation or configuration errors + +Error precedence: ServiceError → LocalError → azcore.ResponseError → gRPC auth → fallback + +## First-Party Extensions + +First-party extensions live in `cli/azd/extensions/` and are registered in `cli/azd/extensions/registry.json`. + +## Detailed Reference + +- [Extension Framework Guide](../../cli/azd/docs/extensions/extension-framework.md) — Getting started +- [Extension Framework Services](../../cli/azd/docs/extensions/extension-framework-services.md) — Adding language support +- [Extensions Style Guide](../../cli/azd/docs/extensions/extensions-style-guide.md) — Design guidelines +- [Creating an Extension](../guides/creating-an-extension.md) — Step-by-step guide diff --git a/docs/architecture/provisioning-pipeline.md b/docs/architecture/provisioning-pipeline.md new file mode 100644 index 00000000000..c6c119b9177 --- /dev/null +++ b/docs/architecture/provisioning-pipeline.md @@ -0,0 +1,75 @@ +# Provisioning Pipeline + +How infrastructure provisioning works in azd. + +## Overview + +The provisioning pipeline creates or updates Azure infrastructure from Infrastructure as Code (IaC) templates. It is triggered by `azd provision` or as part of `azd up`. + +## Pipeline Stages + +```text +IaC Templates → Compilation → Preflight Checks → Deployment → State Tracking +``` + +### 1. Template Compilation + +azd supports two IaC providers: + +- **Bicep** (default) — Compiled to ARM templates via the Bicep CLI +- **Terraform** — Planned and applied via the Terraform CLI + +For Bicep, azd can generate a fully resolved deployment snapshot using `bicep snapshot`, which evaluates expressions, applies conditions, expands copy loops, and flattens nested deployments. + +### 2. Preflight Checks + +Client-side validation that runs after compilation but before deployment: + +- **Role assignment permissions** — Checks if the user has required RBAC roles +- **Resource conflicts** — Detects soft-deleted resources that would conflict +- **Quota availability** — Validates resource quotas (e.g., AI model capacity) +- **Location support** — Verifies resource types are available in the target region + +Preflight checks are pluggable — new checks can be added via `AddCheck()`. + +**UX behavior:** + +- No issues → proceed silently +- Warnings only → display and prompt to continue +- Errors → display and abort + +Disable with: `azd config set provision.preflight off` + +### 3. Deployment + +The compiled template is submitted to Azure Resource Manager (ARM) for deployment. azd monitors the deployment progress and displays status updates. + +### 4. Provision State + +After deployment, azd stores a hash of the template and parameters. On subsequent runs: + +- If the hash matches → provisioning is skipped (no changes detected) +- If the hash differs → provisioning proceeds +- Use `--no-state` to force provisioning regardless + +> **Note:** Provision state does not detect out-of-band changes made via the Azure Portal or other tools. + +## Infrastructure Providers + +### Bicep + +- Default provider for azd projects +- Templates in `infra/` directory (convention: `main.bicep`) +- Compiled to ARM templates before deployment +- Supports modules, parameters, and outputs + +### Terraform + +- Alternative provider, configured in `azure.yaml` +- Uses standard Terraform workflow (init, plan, apply) +- State managed by Terraform (not azd provision state) + +## Detailed Reference + +- [Provision State](../../cli/azd/docs/provision-state.md) — Hash-based change detection +- [Local Preflight Validation](../../cli/azd/docs/design/local-preflight-validation.md) — Preflight check design diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md new file mode 100644 index 00000000000..8eeb0b1de29 --- /dev/null +++ b/docs/architecture/system-overview.md @@ -0,0 +1,95 @@ +# System Overview + +High-level architecture of the Azure Developer CLI. + +## Entry Points + +```text +cli/azd/main.go → cmd/root.go (command tree) → cmd/container.go (IoC registration) +``` + +- **`main.go`** — Application entry point; initializes the root command +- **`cmd/root.go`** — Registers the entire command tree using ActionDescriptors +- **`cmd/container.go`** — Registers all services in the IoC container + +## Directory Structure + +```text +cli/azd/ +├── main.go # Entry point +├── cmd/ # Command definitions (ActionDescriptor pattern) +│ ├── root.go # Command tree registration +│ ├── container.go # IoC service registration +│ ├── actions/ # Action framework (interfaces, results) +│ └── middleware/ # Cross-cutting concerns (telemetry, hooks, extensions) +├── pkg/ # Reusable public packages +│ ├── ioc/ # Dependency injection container +│ ├── project/ # Project configuration (azure.yaml), service targets, frameworks +│ ├── infra/ # Infrastructure providers (Bicep, Terraform) +│ ├── azapi/ # Azure API clients +│ └── tools/ # External tool wrappers (bicep, gh, pack, etc.) +├── internal/ # Internal packages (telemetry, tracing, terminal) +├── test/ # Test utilities and functional tests +├── extensions/ # First-party extensions +└── docs/ # Implementation-level documentation +``` + +## Key Subsystems + +### Command Execution + +Commands follow the ActionDescriptor → CobraBuilder → Cobra pipeline: + +1. ActionDescriptors define commands declaratively in `cmd/root.go` +2. CobraBuilder transforms descriptors into Cobra commands at startup +3. Middleware wraps command execution for telemetry, hooks, and extensions +4. Actions implement the business logic via the `actions.Action` interface + +See [Command Execution Model](command-execution-model.md) for details. + +### Dependency Injection + +All services are registered in `cmd/container.go` using the IoC container (`pkg/ioc`). Services are resolved at runtime — never instantiated directly. + +```go +ioc.RegisterSingleton(container, func() *MyService { + return &MyService{dep: ioc.Get[*Dependency](container)} +}) +``` + +### Infrastructure Provisioning + +The provisioning pipeline compiles IaC templates, runs preflight checks, deploys to Azure, and tracks state: + +1. Compile Bicep/Terraform templates +2. Run local preflight validation (permissions, resource conflicts) +3. Submit deployment to Azure Resource Manager +4. Track provision state hash for change detection + +See [Provisioning Pipeline](provisioning-pipeline.md) for details. + +### Extension Framework + +Extensions communicate via gRPC and can provide new capabilities: + +1. Extensions are discovered from registries (local or remote) +2. azd launches extension processes and connects via gRPC +3. Extensions implement capability interfaces (framework, service target, event handler, etc.) +4. The middleware pipeline routes events to registered extensions + +See [Extension Framework](extension-framework.md) for details. + +### Telemetry + +OpenTelemetry-based tracing with centralized event prefixes: + +- Command events: `cmd.*` +- VS Code RPC events: `vsrpc.*` +- MCP tool events: `mcp.*` + +See [Observability Guide](../guides/observability.md) for instrumentation details. + +## Related Resources + +- [AGENTS.md](../../AGENTS.md) — Quick reference for AI coding agents +- [azd Style Guide](../../cli/azd/docs/style-guidelines/azd-style-guide.md) — Code and UX standards diff --git a/docs/concepts/alpha-features.md b/docs/concepts/alpha-features.md new file mode 100644 index 00000000000..78391cdd765 --- /dev/null +++ b/docs/concepts/alpha-features.md @@ -0,0 +1,51 @@ +# Alpha Features + +Alpha features are experimental capabilities under active development. They are gated behind feature flags and carry no stability guarantees. + +## Enabling Alpha Features + +### Per-feature + +```bash +azd config set alpha. on +azd config set alpha. off +``` + +### All alpha features + +```bash +azd config set alpha.all on +``` + +### In CI/CD + +Set an environment variable for each feature: + +```bash +export AZD_ALPHA_ENABLE_=true +``` + +## Discovering Available Features + +```bash +azd config list-alpha +``` + +This lists all currently available experimental features and their enabled/disabled status. + +## What to Expect + +- **No stability guarantees** — APIs, behavior, and configuration may change without notice +- **Possible removal** — Features may be pulled entirely if the approach doesn't work out +- **Feedback welcome** — Alpha features exist to collect signal; report issues and share impressions + +## Adding a New Alpha Feature + +When implementing a new alpha feature: + +1. Register the feature flag in the alpha features configuration +2. Guard all feature codepaths behind the flag check +3. Document the feature in `azd config list-alpha` output +4. Add a note in release changelog under the experiments section + +For implementation details, see [cli/azd/docs/alpha-features.md](../../cli/azd/docs/alpha-features.md). diff --git a/docs/concepts/feature-stages.md b/docs/concepts/feature-stages.md new file mode 100644 index 00000000000..429c931ccc5 --- /dev/null +++ b/docs/concepts/feature-stages.md @@ -0,0 +1,39 @@ +# Feature Stages + +azd uses a three-stage lifecycle to graduate features from experimental to fully supported. + +## Stages + +### Alpha + +- Behind a feature flag — must be explicitly opted into +- Enable per-feature: `azd config set alpha. on` +- Enable all: `azd config set alpha.all on` +- In CI: set `AZD_ALPHA_ENABLE_=true` +- No stability guarantees — may be removed or redesigned +- Discoverable via `azd config list-alpha` + +### Beta + +- Available by default (no feature flag needed) +- Functional and supported, but may undergo breaking changes +- Actively collecting user feedback + +### Stable + +- Fully supported with backward compatibility guarantees +- Complete documentation on [aka.ms/azd](https://aka.ms/azd) +- Breaking changes follow a deprecation process + +## Graduation Criteria + +For a feature to move from alpha → beta: + +1. Feature is spec'd and approved +2. Formal PM, engineering, and design review completed +3. Documented on DevHub and in CLI help text +4. Positive user feedback signal + +For the current status of all features, see [Feature Status](../reference/feature-status.md). + +For implementation details on the alpha feature flag system, see [cli/azd/docs/alpha-features.md](../../cli/azd/docs/alpha-features.md). diff --git a/docs/concepts/glossary.md b/docs/concepts/glossary.md new file mode 100644 index 00000000000..316c57adffd --- /dev/null +++ b/docs/concepts/glossary.md @@ -0,0 +1,111 @@ +# Glossary + +Key terms and concepts used throughout the Azure Developer CLI codebase. + +## Core Concepts + +### azd (Azure Developer CLI) + +A Go-based CLI tool for Azure application development and deployment. Handles infrastructure provisioning, application deployment, environment management, and service lifecycle hooks. + +### azure.yaml + +The project configuration file that defines an azd project. Located at the root of a project, it declares services, their language/framework, hosting targets, and hooks. See [azure.yaml Schema](../reference/azure-yaml-schema.md). + +### Environment + +A named collection of configuration values and secrets stored locally (and optionally in a remote backend). Environments let you target different deployment configurations (e.g., `dev`, `staging`, `prod`) from the same project. + +### Service + +A deployable unit defined in `azure.yaml`. Each service has a source path, a language/framework, and a host target. Services are built, packaged, and deployed independently during `azd deploy`. + +### Service Target (Host) + +The Azure resource that hosts a deployed service. Supported targets include Azure App Service, Azure Container Apps, Azure Functions, Azure Static Web Apps, Azure Kubernetes Service (AKS), and Azure AI. + +### Framework Service + +A language/build framework that knows how to restore, build, and package a service's source code. Built-in frameworks include .NET, Python, Java, JavaScript/TypeScript, and Docker. Extensions can add support for additional frameworks. + +## Infrastructure + +### Bicep + +The default Infrastructure as Code (IaC) language for azd. Bicep templates declare Azure resources and are compiled to ARM templates before deployment. + +### Terraform + +An alternative IaC provider supported by azd. Terraform configurations use HCL syntax to declare Azure resources. + +### Provisioning + +The process of creating or updating Azure infrastructure from IaC templates. Triggered by `azd provision` or as part of `azd up`. + +### Provision State + +A hash-based mechanism that tracks whether the IaC template has changed since the last deployment. Provisioning is skipped when the template hash matches the previous deployment, unless `--no-state` is passed. + +### Preflight Checks + +Client-side validation that runs after Bicep compilation but before server-side deployment. Checks resource availability, permissions, and potential conflicts to surface issues early. + +## Extensions + +### Extension + +A plugin that extends azd functionality via a gRPC-based framework. Extensions can add new commands, service targets, framework providers, event handlers, and more. First-party extensions live in `cli/azd/extensions/`. + +### Extension Registry + +A JSON manifest that lists available extensions, their versions, capabilities, and download URLs. The official registry is hosted at `https://aka.ms/azd/extensions/registry`. + +### Extension Capabilities + +The set of features an extension provides. Capabilities include: event handlers, framework service providers, service target providers, compose providers, workflow providers, and various gRPC services. + +## Architecture + +### ActionDescriptor + +The pattern used to define CLI commands. Each command is described by an `ActionDescriptor` that specifies its metadata, flags, output formats, and the action implementation to resolve via IoC. + +### Action + +The interface that command implementations satisfy. Actions have a `Run(ctx context.Context) (*ActionResult, error)` method that executes the command logic. + +### IoC Container + +The dependency injection container (`pkg/ioc`) used throughout azd. All services are registered at startup in `cmd/container.go` and resolved via the container at runtime. + +### Middleware + +Cross-cutting concerns that wrap command execution. Middleware handles telemetry, hooks, extensions, and other concerns that apply across multiple commands. + +### Hooks + +User-defined scripts that run at specific lifecycle points (pre/post provision, pre/post deploy, etc.). Hooks are declared in `azure.yaml` and executed by the middleware pipeline. + +## Feature Lifecycle + +### Alpha Feature + +An experimental feature behind a feature flag. Enabled via `azd config set alpha. on` or `AZD_ALPHA_ENABLE_=true`. No stability guarantees. + +### Beta Feature + +A feature that is functional and supported but may undergo breaking changes. Beta features are available by default without feature flags. + +### Stable Feature + +A fully supported feature with backward compatibility guarantees and complete documentation. + +## Development + +### Snapshot Testing + +A testing approach where command help output is captured and compared against saved snapshots. Updated via `UPDATE_SNAPSHOTS=true go test ./cmd -run 'TestFigSpec|TestUsage'`. + +### Fig Spec + +A shell completion specification generated from the CLI command tree. Used to provide rich tab-completion in terminals that support Fig/autocomplete. diff --git a/docs/guides/adding-a-new-command.md b/docs/guides/adding-a-new-command.md new file mode 100644 index 00000000000..76459bd37bc --- /dev/null +++ b/docs/guides/adding-a-new-command.md @@ -0,0 +1,98 @@ +# Adding a New Command + +This guide walks through adding a new command to the Azure Developer CLI. + +## Overview + +azd uses an **ActionDescriptor** pattern to define commands. Each command consists of: + +1. **ActionDescriptor** — Declares the command's metadata, flags, and output formats +2. **Action** — Implements `Run(ctx context.Context) (*ActionResult, error)` +3. **Flags struct** — Defines command-line flags with a `Bind()` method +4. **IoC registration** — Wires the action and flags into the dependency injection container + +## Quick Start + +### 1. Create the command file + +Create `cli/azd/internal/cmd/.go`: + +```go +package cmd + +import ( + "context" + "github.com/azure/azure-dev/cli/azd/cmd/actions" +) + +type myCommandFlags struct { + name string +} + +func (f *myCommandFlags) Bind(local *pflag.FlagSet, global *pflag.FlagSet) { + local.StringVar(&f.name, "name", "", "Resource name") +} + +type myCommandAction struct { + flags *myCommandFlags + svc *SomeService +} + +func newMyCommandAction(flags *myCommandFlags, svc *SomeService) actions.Action { + return &myCommandAction{flags: flags, svc: svc} +} + +func (a *myCommandAction) Run(ctx context.Context) (*actions.ActionResult, error) { + // Command logic here + return &actions.ActionResult{ + Message: &actions.ResultMessage{Header: "Done!"}, + }, nil +} +``` + +### 2. Register the command + +Add to the command tree in `cli/azd/cmd/root.go`: + +```go +group.Add("mycommand", &actions.ActionDescriptorOptions{ + Command: newMyCommandCmd(), + ActionResolver: newMyCommandAction, + FlagsResolver: newMyCommandFlags, +}) +``` + +### 3. Support output formats + +If the command produces structured output, add format support: + +```go +group.Add("mycommand", &actions.ActionDescriptorOptions{ + Command: newMyCommandCmd(), + ActionResolver: newMyCommandAction, + FlagsResolver: newMyCommandFlags, + OutputFormats: []actions.OutputFormat{actions.OutputFormatJson, actions.OutputFormatTable}, +}) +``` + +### 4. Update snapshots + +After adding the command, regenerate CLI snapshots: + +```bash +UPDATE_SNAPSHOTS=true go test ./cmd -run 'TestFigSpec|TestUsage' +``` + +## Design Principles + +- **Verb-first structure:** Use simple verbs (`up`, `add`, `deploy`) with minimal nesting +- **Build on existing categories:** Extend existing command groups rather than creating new ones +- **Progressive disclosure:** Basic usage should be simple; advanced features discoverable when needed +- **Consistent parameters:** Reuse established flag patterns (`--subscription`, `--name`, `--output`) + +## Detailed Reference + +For the full implementation guide including middleware, telemetry integration, and advanced patterns, see: + +- [cli/azd/docs/style-guidelines/new-azd-command.md](../../cli/azd/docs/style-guidelines/new-azd-command.md) +- [Guiding Principles](../../cli/azd/docs/style-guidelines/guiding-principles.md) diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md new file mode 100644 index 00000000000..e590620d88c --- /dev/null +++ b/docs/guides/contributing.md @@ -0,0 +1,94 @@ +# Contributing to Azure Developer CLI + +This guide covers how to build, test, lint, and submit changes to the Azure Developer CLI. + +## Prerequisites + +- Go 1.26 or later +- [golangci-lint](https://golangci-lint.run/) +- [cspell](https://cspell.org/) (for spell checking) + +## Build + +From `cli/azd/`: + +```bash +go build +``` + +## Test + +```bash +# Run a specific test +go test ./pkg/project/... -run TestProjectConfig + +# Run unit tests only (may take up to 10 minutes) +go test ./... -short + +# Run full suite including end-to-end tests +go test ./... +``` + +> **Note:** In CI environments, run `go build` first — the automatic build is skipped and the azd binary must exist for tests that spawn the CLI process. + +### Snapshot Tests + +When command help text changes or new commands are added, update snapshots: + +```bash +UPDATE_SNAPSHOTS=true go test ./cmd -run 'TestFigSpec|TestUsage' +``` + +## Pre-Commit Checklist + +Run all checks from `cli/azd/`: + +```bash +gofmt -s -w . +go fix ./... +golangci-lint run ./... +cspell lint "**/*.go" --relative --config ./.vscode/cspell.yaml --no-progress +../../eng/scripts/copyright-check.sh . --fix +``` + +### What each check does + +| Check | Purpose | +|---|---| +| `gofmt -s -w .` | Formats Go code to standard style | +| `go fix ./...` | Applies automatic modernizations (e.g., `interface{}` → `any`) | +| `golangci-lint run ./...` | Runs linters including line length, security, and static analysis | +| `cspell lint` | Checks spelling; add new terms to `.vscode/cspell.yaml` overrides | +| `copyright-check.sh` | Ensures all Go files have the Microsoft copyright header | + +## Key Lint Rules + +- **Line length:** 125 characters max (enforced by `lll` linter) +- **Formatting:** Standard Go formatting via `gofmt` +- **Security:** `gosec` checks for common security issues +- **Error handling:** `errorlint` enforces correct `errors.Is`/`errors.As`/`errors.AsType` usage +- **Unused code:** `unused` detects dead code +- **Static analysis:** `staticcheck` provides comprehensive checks + +## Code Style + +- **Import order:** stdlib → external → azure/azd internal → local +- **Error handling:** Wrap errors with `fmt.Errorf("context: %w", err)` +- **Context propagation:** Pass `ctx context.Context` as the first parameter to I/O functions +- **Modern Go:** Use Go 1.26+ features — see [AGENTS.md](../../AGENTS.md) for the full list +- **Testing:** Prefer table-driven tests; use testify/mock for mocking + +For comprehensive style guidance, see: + +- [azd Style Guide](../../cli/azd/docs/style-guidelines/azd-style-guide.md) +- [Guiding Principles](../../cli/azd/docs/style-guidelines/guiding-principles.md) + +## Submitting Changes + +1. Fork the repository and create a feature branch +2. Make your changes following the code style guidelines +3. Run the pre-commit checklist +4. Run relevant tests +5. Open a pull request with a clear description of your changes + +Most contributions require a [Contributor License Agreement (CLA)](https://cla.microsoft.com). A bot will guide you through this when you open a PR. diff --git a/docs/guides/creating-an-extension.md b/docs/guides/creating-an-extension.md new file mode 100644 index 00000000000..bad8ab01fa0 --- /dev/null +++ b/docs/guides/creating-an-extension.md @@ -0,0 +1,78 @@ +# Creating an Extension + +This guide covers how to create, build, and publish an extension for the Azure Developer CLI. + +## Overview + +azd extensions use a gRPC-based framework to add functionality. Extensions can provide: + +- **Event handlers** — React to lifecycle events (pre/post provision, deploy, etc.) +- **Framework service providers** — Add build/restore support for new languages +- **Service target providers** — Add deployment support for new Azure hosting targets +- **Compose providers** — Custom orchestration logic +- **Workflow providers** — Custom workflow steps +- **gRPC services** — Project, Environment, User Config, Deployment, Account, Prompt, AI Model, and more + +## Prerequisites + +- Go 1.26 or later +- A fork of the [azure-dev](https://github.com/Azure/azure-dev) repository +- The `azd` Developer Extension installed (`azd extension install azd.dev`) + +## Getting Started + +### 1. Create the extension + +First-party extensions live under `cli/azd/extensions/`. Create a new directory for your extension: + +```bash +mkdir -p cli/azd/extensions/my.extension +cd cli/azd/extensions/my.extension +``` + +### 2. Define extension.yaml + +Create an `extension.yaml` manifest that declares the extension's metadata and capabilities: + +```yaml +name: my.extension +displayName: My Extension +description: A brief description of what this extension does +version: 0.1.0 +capabilities: + - event-handler +``` + +### 3. Implement the extension + +Implement the required interfaces for your declared capabilities. See the extension framework services documentation for interface details. + +### 4. Build + +```bash +# Using the developer extension +azd x build + +# Or using Go directly +go build +``` + +### 5. Register in the extension registry + +For first-party extensions, add an entry to `cli/azd/extensions/registry.json` with version, capabilities, and download URLs. + +## Extension Design Guidelines + +- **Extend existing command categories** — Use verb-first structure (e.g., `azd add `) +- **Reuse parameter patterns** — Use established flags like `--subscription`, `--name`, `--type` +- **Integrate with help** — Make your extension discoverable through `azd help` +- **Error handling** — Use `ServiceError` for Azure API errors and `LocalError` for client-side errors +- **Telemetry** — Follow pattern-based classification (e.g., `ext.service.`) + +## Detailed Reference + +For comprehensive extension development documentation, see: + +- [Extension Framework](../../cli/azd/docs/extensions/extension-framework.md) — Full framework guide +- [Extension Framework Services](../../cli/azd/docs/extensions/extension-framework-services.md) — Adding language/framework support +- [Extensions Style Guide](../../cli/azd/docs/extensions/extensions-style-guide.md) — Design guidelines and best practices diff --git a/docs/guides/observability.md b/docs/guides/observability.md new file mode 100644 index 00000000000..f8e9eeb0e51 --- /dev/null +++ b/docs/guides/observability.md @@ -0,0 +1,80 @@ +# Observability and Tracing + +This guide covers how to add telemetry, inspect traces, and debug the Azure Developer CLI. + +## Tracing Architecture + +azd uses [OpenTelemetry](https://opentelemetry.io/) to collect anonymous usage information and success metrics. The internal tracing package at `cli/azd/internal/tracing` wraps the standard OpenTelemetry library. + +All commands automatically create a root command event with a `cmd.` namespace prefix (e.g., `cmd.provision`, `cmd.up`). + +## Key Concepts + +- **Trace** — Represents an entire operation or command (e.g., `azd up`) +- **Span** (Event) — A single unit of work within an operation (e.g., deploying a resource) +- **Attribute** — Metadata attached to a span (e.g., environment name, subscription ID) + +## Viewing Traces Locally + +### Write to file + +```bash +azd provision --trace-log-file traces.json +``` + +### Send to Jaeger + +Start a local Jaeger instance: + +```bash +docker run -d --name jaeger \ + -e COLLECTOR_OTLP_ENABLED=true \ + -e JAEGER_DISABLED=true \ + -p 16686:16686 \ + -p 4318:4318 \ + jaegertracing/all-in-one +``` + +Then pass the endpoint to any command: + +```bash +azd provision --trace-log-url localhost +``` + +View results at [http://localhost:16686/search](http://localhost:16686/search). + +## Adding New Telemetry + +### Event Name Prefixes + +Telemetry prefixes are centralized in `internal/tracing/events`: + +| Prefix | Usage | +|---|---| +| `cmd.` | CLI command events | +| `vsrpc.` | VS Code RPC events | +| `mcp.` | MCP tool events | + +Use the constants from `internal/tracing/events/events.go` rather than string literals. + +### Adding an Attribute + +Attach metadata to an existing span: + +```go +span.SetAttributes(attribute.String("my.attribute", value)) +``` + +### Adding an Event (Span) + +Create a new span for a unit of work: + +```go +ctx, span := tracing.Start(ctx, "mypackage.operation") +defer span.End() +``` + +## Detailed Reference + +- [Tracing in azd](../../cli/azd/docs/tracing-in-azd.md) — Full tracing implementation guide +- [Observability](../../cli/azd/docs/observability.md) — Trace output configuration diff --git a/docs/reference/azure-yaml-schema.md b/docs/reference/azure-yaml-schema.md new file mode 100644 index 00000000000..31630ad68a2 --- /dev/null +++ b/docs/reference/azure-yaml-schema.md @@ -0,0 +1,69 @@ +# azure.yaml Schema + +The `azure.yaml` file is the project configuration file for the Azure Developer CLI. It lives at the root of your project and declares services, infrastructure, and lifecycle hooks. + +## Overview + +```yaml +name: my-project +metadata: + template: my-org/my-template +services: + web: + project: ./src/web + language: js + host: appservice + api: + project: ./src/api + language: python + host: containerapp +``` + +## Top-Level Properties + +| Property | Type | Description | +|---|---|---| +| `name` | string | **Required.** Project name used for resource naming | +| `metadata` | object | Template metadata (origin template, version) | +| `resourceGroup` | string | Override the default resource group name | +| `services` | map | Service definitions keyed by service name | +| `pipeline` | object | CI/CD pipeline configuration | +| `hooks` | map | Project-level lifecycle hooks | +| `infra` | object | Infrastructure provider configuration | +| `state` | object | Remote state backend configuration | + +## Service Properties + +| Property | Type | Description | +|---|---|---| +| `project` | string | **Required.** Relative path to the service source directory | +| `language` | string | Service language (`dotnet`, `py`, `js`, `ts`, `java`, `docker`) | +| `host` | string | Hosting target (`appservice`, `containerapp`, `function`, `staticwebapp`, `aks`, `ai`) | +| `module` | string | Bicep module path for the service's infrastructure | +| `hooks` | map | Service-level lifecycle hooks | +| `docker` | object | Docker build configuration | + +## Hooks + +Hooks run user-defined scripts at lifecycle points: + +```yaml +hooks: + preprovision: + shell: sh + run: ./scripts/setup.sh + postdeploy: + shell: sh + run: ./scripts/smoke-test.sh +``` + +Available hook points: `prerestore`, `postrestore`, `preprovision`, `postprovision`, `predeploy`, `postdeploy`, `prepackage`, `postpackage`, `predown`, `postdown`. + +## JSON Schema + +The full JSON schema for `azure.yaml` is maintained in the [schemas/](../../schemas/) directory and published for editor validation. + +## See Also + +- [azure.yaml JSON Schema](../../schemas/) — Machine-readable schema definition +- [Feature Status](feature-status.md) — Which languages and hosts are stable/beta/alpha diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md new file mode 100644 index 00000000000..1ec3518a336 --- /dev/null +++ b/docs/reference/environment-variables.md @@ -0,0 +1,53 @@ +# Environment Variables + +Environment variables that configure Azure Developer CLI behavior. These can be set in your shell, CI/CD pipeline, or `.env` files. + +## Feature Flags + +| Variable | Description | +|---|---| +| `AZD_ALPHA_ENABLE_` | Enable a specific alpha feature (e.g., `AZD_ALPHA_ENABLE_UPDATE=true`) | + +## Authentication + +| Variable | Description | +|---|---| +| `AZD_AUTH_ENDPOINT` | Custom authentication endpoint URL | +| `AZD_AUTH_KEY` | Authentication key for external auth providers | + +## Configuration + +| Variable | Description | +|---|---| +| `AZD_CONFIG_DIR` | Override the default user configuration directory | +| `AZURE_DEV_COLLECT_TELEMETRY` | Set to `no` to disable telemetry collection | + +## Behavior + +| Variable | Description | +|---|---| +| `AZD_DEMO_MODE` | When set, hides PII (e.g., subscription IDs) in output | +| `AZD_FORCE_TTY` | Force TTY detection (`true` enables, `false` disables prompting) | +| `AZD_IN_CLOUDSHELL` | Indicates azd is running in Azure Cloud Shell | +| `AZD_SKIP_UPDATE_CHECK` | Skip the periodic update availability check | +| `AZD_DEBUG_DOTENV_OVERRIDES` | Enable debug logging for `.env` file processing | + +## Tool Path Overrides + +Override the path to external tools that azd invokes: + +| Variable | Description | +|---|---| +| `AZD_BICEP_TOOL_PATH` | Path to the Bicep CLI binary | +| `AZD_GH_TOOL_PATH` | Path to the GitHub CLI binary | +| `AZD_PACK_TOOL_PATH` | Path to the Cloud Native Buildpacks (`pack`) binary | + +## Build Configuration + +| Variable | Description | +|---|---| +| `AZD_BUILDER_IMAGE` | Builder image for Dockerfile-less container builds | + +## See Also + +For the full reference with implementation details, see [cli/azd/docs/environment-variables.md](../../cli/azd/docs/environment-variables.md). diff --git a/docs/reference/feature-status.md b/docs/reference/feature-status.md new file mode 100644 index 00000000000..a09e80cb243 --- /dev/null +++ b/docs/reference/feature-status.md @@ -0,0 +1,76 @@ +# Feature Status + +Current maturity status of Azure Developer CLI features. See [Feature Stages](../concepts/feature-stages.md) for what each stage means. + +## Commands + +| Feature | Stage | +|---|---| +| `config` | Stable | +| `deploy` | Stable | +| `down` | Stable | +| `env` | Stable | +| `provision` | Stable | +| `up` | Stable | +| `monitor` | Beta | +| `pipeline` | Beta | +| `restore` | Beta | +| `template` | Beta | +| `package` | Beta | +| `add` | Beta | + +## Languages + +| Language | Stage | +|---|---| +| Python | Stable | +| JavaScript / TypeScript | Stable | +| Java | Stable | +| .NET (C#) | Stable | + +## Infrastructure as Code + +| Provider | Stage | +|---|---| +| Bicep | Stable | +| Terraform | Beta | + +## Hosting Targets + +| Host | Stage | +|---|---| +| Azure App Service | Stable | +| Azure Static Web Apps | Stable | +| Azure Container Apps | Stable | +| Azure Functions | Stable | +| Azure Kubernetes Service (AKS) | Beta | +| Azure AI | Beta | + +## Clients + +| Client | Stage | +|---|---| +| VS Code Extension | Beta | +| Codespaces | Beta | +| Cloud Shell | Beta | +| Visual Studio | Alpha | + +## CI/CD + +| Platform | Stage | +|---|---| +| GitHub Actions | Stable | +| Azure Pipelines | Stable | + +## Advanced Features + +| Feature | Stage | +|---|---| +| Resource Group deployments | Beta | +| Layered Provisioning | Beta | +| Deployment Stacks | Alpha | +| Extensions | Alpha | + +--- + +For the full feature tracking table with graduation criteria, see [cli/azd/docs/feature-stages.md](../../cli/azd/docs/feature-stages.md). From 5ba9d8d2a87b764594a0a24c7e269eaf86a38e7e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Mar 2026 14:28:27 +0000 Subject: [PATCH 3/5] Address code review: alphabetize feature status, improve action docs Co-authored-by: spboyer <7681382+spboyer@users.noreply.github.com> --- docs/architecture/command-execution-model.md | 2 +- docs/reference/feature-status.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/architecture/command-execution-model.md b/docs/architecture/command-execution-model.md index 69da6e044c7..327665f115c 100644 --- a/docs/architecture/command-execution-model.md +++ b/docs/architecture/command-execution-model.md @@ -57,7 +57,7 @@ type Action interface { } ``` -Actions receive dependencies via constructor injection through the IoC container. They return an `ActionResult` with a message and optional structured data for output formatting. +The `ActionResult` contains a `Message` (displayed to the user) and optional structured data used by output formatters (JSON, table). Actions receive dependencies via constructor injection through the IoC container. ### 5. Output Formatting diff --git a/docs/reference/feature-status.md b/docs/reference/feature-status.md index a09e80cb243..77819070782 100644 --- a/docs/reference/feature-status.md +++ b/docs/reference/feature-status.md @@ -6,18 +6,18 @@ Current maturity status of Azure Developer CLI features. See [Feature Stages](.. | Feature | Stage | |---|---| +| `add` | Beta | | `config` | Stable | | `deploy` | Stable | | `down` | Stable | | `env` | Stable | -| `provision` | Stable | -| `up` | Stable | | `monitor` | Beta | +| `package` | Beta | | `pipeline` | Beta | +| `provision` | Stable | | `restore` | Beta | | `template` | Beta | -| `package` | Beta | -| `add` | Beta | +| `up` | Stable | ## Languages From 212d209be65b1e829b65a197dad32f8ce3b574e4 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Fri, 20 Mar 2026 13:02:14 -0400 Subject: [PATCH 4/5] fix: resolve cspell failures and review feedback - Add cspell overrides for technical terms in docs/ markdown files - Fix Jaeger OTLP endpoint to use explicit http://localhost:4318 - Update AGENTS.md link in README.md to root (symlink) - Verified errors.AsType is valid (Go 1.26, used in 10+ files) - Verified table syntax is correct (no || issues found) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .vscode/cspell.misc.yaml | 26 ++++++++++++++++++++++++++ README.md | 2 +- docs/guides/observability.md | 2 +- 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/.vscode/cspell.misc.yaml b/.vscode/cspell.misc.yaml index 66a501e4eb8..4663c6d2b5e 100644 --- a/.vscode/cspell.misc.yaml +++ b/.vscode/cspell.misc.yaml @@ -36,3 +36,29 @@ overrides: - azureai - entra - flexconsumption + - filename: docs/architecture/**/*.md + words: + - azapi + - Errorf + - grpcbroker + - vsrpc + - filename: docs/guides/**/*.md + words: + - errorlint + - Errorf + - gofmt + - golangci + - gosec + - jaegertracing + - mycommand + - mypackage + - pflag + - staticcheck + - stdlib + - vsrpc + - filename: docs/reference/**/*.md + words: + - appservice + - Buildpacks + - containerapp + - staticwebapp diff --git a/README.md b/README.md index 21d12710450..7f7c5f5eb43 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ ## 🤖 AI Agents -**Contributing to this repo?** See [AGENTS.md](cli/azd/AGENTS.md) for coding standards and [docs/](docs/README.md) for contributor documentation. +**Contributing to this repo?** See [AGENTS.md](AGENTS.md) for coding standards and [docs/](docs/README.md) for contributor documentation. **Using `azd` with an AI coding assistant?** Check out the [docs](https://aka.ms/azd) and [templates](https://azure.github.io/awesome-azd/). diff --git a/docs/guides/observability.md b/docs/guides/observability.md index f8e9eeb0e51..a39ad71f95b 100644 --- a/docs/guides/observability.md +++ b/docs/guides/observability.md @@ -38,7 +38,7 @@ docker run -d --name jaeger \ Then pass the endpoint to any command: ```bash -azd provision --trace-log-url localhost +azd provision --trace-log-url http://localhost:4318 ``` View results at [http://localhost:16686/search](http://localhost:16686/search). From d1eb6e09f39746df7bca7fc3bf0b815265009096 Mon Sep 17 00:00:00 2001 From: Shayne Boyer Date: Fri, 20 Mar 2026 13:26:05 -0400 Subject: [PATCH 5/5] chore: retrigger CI