Instruction file imported from Azure/azure-sdk-for-js (.github/instructions/reviewer/mgmt-sdk.instructions.md). Copyright stays with the author.

Management SDK Review — ARM Package Patterns

Scope: Public API + tool validation for @azure/arm-* packages. Review src/, review/*.api.md, README, CHANGELOG, samples, snippets.spec.ts. Skip implementation internals, private methods. Only flag issues introduced by this PR.

ARM packages are auto-generated from TypeSpec or Swagger. Review focuses on public API surface and rule-based validations.

Version Consistency (Tool Validation)

Package version must align across:

• package.json — source of truth
• src/api/*Context.ts (e.g., managedOpsContext.ts) — discover the appropriate *Context.ts file first
• CHANGELOG.md top heading

Cross-check code references in README, snippets.spec.ts, and public API. Inconsistent versions → critical tool issue.

Version rules:

• First package version must be preview (regardless of API versions)
• Preview API versions can only ship in preview package versions
• No alpha versions anywhere (CHANGELOG.md, context files, package.json)
• First CHANGELOG entry is hard-coded template — ignore content, only check version matches

Breaking Changes

Breaking changes are acceptable in mgmt SDKs with proper CHANGELOG documentation.

Root-cause analysis: Trace breaking changes to their source:

• API version change in spec → expected, document in changelog
• TypeSpec migration artifact → may be approved pattern, check with architects
• Emitter/tooling bug → report to typespec-azure
• Do NOT flag cosmetic changes: XxxOptionalParams→XxxOptions, response wrapper removal

Changelog alignment: Public API changes in review/*.api.md must be documented:

• New exports → Features Added
• Removed/renamed exports → Breaking Changes with migration guidance

Naming Validation (Spec Issues)

Flag patterns indicating spec problems:

• _N suffixes (e.g., Resource_1) → duplicated models, use @clientName
• AutoGenerated suffixes → duplicated Swagger models, merge in spec
• _ prefixes on enums → use @clientName for better name

Type Safety

• Avoid unknown in return types
• Avoid unknown in public models (exception: ErrorAdditionalInfo)
• No void return for create/update/get/list operations (void acceptable for delete/upgrade/reset actions)
• any is acceptable in mgmt SDKs — do NOT flag
• undocumented tags on public API are acceptable — do NOT flag

Exports

• New symbols in src/index.ts must appear in review/{package-name}-node.api.md
• ae-forgotten-export warnings indicate missing exports — usually generation tool bug
• Avoid exports clashing with web/DOM types (Request, Response, Event)

Samples & Tests

• Samples are auto-generated — only comment on syntax issues found while checking src/ references
• Do NOT comment on placeholder values in samples (e.g., subscriptionId, resourceGroupName) — these are intentionally non-real values
• Do NOT comment on style, formatting, documentation, or whitespace
• Do NOT comment on implementation internals (private methods, internal helpers)

Generated Infrastructure Files

• Do NOT comment on eslint.config.mjs, warp.config.yml, tsconfig.json, or vitest.config.ts patterns — these are set by the generation tool and intentionally differ from hand-written packages
• Config deviations from other packages are expected when generation tooling evolves

Comment Deduplication

• If an issue repeats across multiple files (e.g., same placeholder format in every sample), comment ONCE on the first file and note the total count of affected files
• Do NOT post the same comment on every file that has the same issue

Issue Types

🔴 Tool Issue: Generation bug → fix + report to typespec-azure 🔴 Design Issue: API problem → @clientName/@override in spec repo 🔵 Suggestion: Optional improvement