Skip to content

Updating instructions by mining PRs for feedback #8618

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
richardpark-msft wants to merge 2 commits into
base: main
Choose a base branch
from
+27 −0
Draft

Updating instructions by mining PRs for feedback #8618

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc8c5a7
These are some auto-mined instruction updates that should help with s…
Jun 11, 2026
a21285d
Add in a reference to the extensions guideline.
Jun 11, 2026
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
5 changes: 5 additions & 0 deletions .github/instructions/documentation.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.<name>.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._
15 changes: 15 additions & 0 deletions .github/instructions/extensions.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
7 changes: 7 additions & 0 deletions .github/instructions/go.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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._
Loading