diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md index 3f4e44dd8fd..c2f4574d4ad 100644 --- a/.github/instructions/documentation.instructions.md +++ b/.github/instructions/documentation.instructions.md @@ -17,12 +17,14 @@ docs/ ## 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. +- **User-visible behavior change:** Add or update a `CHANGELOG.md` entry when release-note-worthy, and update relevant command docs/help when behavior affects workflows, especially `--no-prompt` or CI/script semantics. - **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`. +- **Product rebrand or compatibility name:** Use the current product name in user-facing prose, while preserving legacy/internal identifiers only where required by code, telemetry, APIs, or compatibility. ## Documentation Placement Guide @@ -42,3 +44,6 @@ docs/ - 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 +- Verify environment-variable docs against source behavior and generated config shapes. Distinguish values that `azd` reads directly from template substitutions, and document Bicep parameter files using the nested `parameters..value` shape rather than flattened JSON. + +_Sources: PR #8494 https://github.com/Azure/azure-dev/pull/8494#discussion_r3327398519; PR #8561 https://github.com/Azure/azure-dev/pull/8561#pullrequestreview-4451043828; PR #8579 https://github.com/Azure/azure-dev/pull/8579#discussion_r3381280690; PR #8529 https://github.com/Azure/azure-dev/issues/8529#issuecomment-4616281158._ diff --git a/.github/instructions/extensions.instructions.md b/.github/instructions/extensions.instructions.md index d303c2696be..82b712fbf54 100644 --- a/.github/instructions/extensions.instructions.md +++ b/.github/instructions/extensions.instructions.md @@ -6,3 +6,18 @@ applyTo: NOT `Subscription.TenantId` (resource tenant). For multi-tenant/guest users these differ, and using `TenantId` causes authentication failures. The `LookupTenant()` API already returns the correct user access tenant. + +- When adding or reviewing destructive extension commands, verify the service + API contract and local cleanup behavior end-to-end: confirm whether the API + supports the requested delete scope, handle empty successful delete responses, + avoid redundant pre-checks that later operations already cover, and clean up + any persisted local state such as conversation or session IDs. + _Source: PR #8519 comments + https://github.com/Azure/azure-dev/pull/8519#discussion_r3357456060, + https://github.com/Azure/azure-dev/pull/8519#discussion_r3357464681, + https://github.com/Azure/azure-dev/pull/8519#discussion_r3357472539, + https://github.com/Azure/azure-dev/pull/8519#discussion_r3357477998._ + +- Follow extension guidelines in: cli/azd/docs/extensions/extensions-style-guide.md. If the work + violates any of these principles, include a link to the guide so the user can read it and get + ahead of some of the problems. diff --git a/.github/instructions/go.instructions.md b/.github/instructions/go.instructions.md index 776ed82003a..af0d17e69f1 100644 --- a/.github/instructions/go.instructions.md +++ b/.github/instructions/go.instructions.md @@ -26,3 +26,10 @@ create a pointer to the given value. This replaces helper functions like Before flagging missing imports or undefined references, verify the symbol isn't already defined in unchanged portions of the file. The diff context may not show all existing imports or declarations. + +## CLI behavior and domain filtering + +- When reviewing command input resolution, explicit CLI args and flags should win over defaults. Do not prompt the user toward a different default when they provided a valid new value; reserve prompts for ambiguous choices and preserve deterministic `--no-prompt` behavior for CI/scripts. +- When filtering AI models or quota data by location, keep location-specific usage data associated with only the models available in that location. Empty or unknown usage data from an unrelated location must not make a model eligible elsewhere; add regression coverage for cross-location quota cases. + +_Sources: PR #8561 https://github.com/Azure/azure-dev/pull/8561#discussion_r3374961004; PR #8537 https://github.com/Azure/azure-dev/pull/8537#discussion_r3364235532._