Azure / Azure/azure-rest-api-specs
ARM API Reviewer agent: add API version lifecycle, branch placement, promotion, TypeSpec conversion, and date-ordering guidance
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 424
Description
## Problem
Neither the ARM reviewer's instructions nor its reference material previously codified where a given API version lifecycle stage (private preview, public preview, GA/stable) is allowed to live: which repository, which branch, and which folder naming convention applies at each stage, how a version is promoted from preview to stable, how a Swagger-authored version converts to TypeSpec mid-lifecycle, and how API version dates must be ordered relative to sibling versions. Without this guidance, the reviewer had no basis to flag:
- a new API version folder placed on the wrong branch or in the wrong repo for its lifecycle stage,
- a promotion from preview to GA that skipped required steps or left a stale preview definition inconsistent with the new stable one,
- a TypeSpec conversion mid-lifecycle that silently changed lifecycle-relevant metadata,
- an API version whose date is out of chronological order relative to existing versions in the same service.
## Evidence
- No `api-version-lifecycle-and-branches.md` (or equivalent) reference file existed prior to this work; the gap was identified during the cross-file consistency audit of PR #45841 while checking whether "branch-independent" folder rules (e.g., a private-preview folder convention) were documented anywhere.
- The audit surfaced a related correction needed once the new reference was added: `APIVER-PRIVATE-FOLDER` needed to be explicitly marked branch-independent, since it was initially miscategorized as branch-scoped, which would have caused false findings on legitimately branch-independent private-preview folders.
- Reviewers had no authoritative rule ID space (`APIVER-*`) to cite for lifecycle findings before this change, so any lifecycle observation had to be raised as unstructured prose rather than a citable, gradeable rule.
## Proposed Solution (implemented in PR #45841)
1. Add `.github/skills/azure-api-review/references/api-version-lifecycle-and-branches.md` as the canonical cross-cutting reference (applies to both OpenAPI and TypeSpec), covering:
- which repo and branch each lifecycle stage (private preview, public preview, GA) may be authored in,
- folder naming and placement conventions, including which are branch-independent (e.g., `APIVER-PRIVATE-FOLDER`),
- the promotion path from preview to stable and what must stay consistent across that transition,
- TypeSpec conversion guidance for a version already in flight,
- date-ordering requirements between sibling API versions.
2. Register the new reference in the `azure-api-review` SKILL.md cross-cutting table with its `APIVER-*` rule ID prefix so both the ARM and data-plane reviewers can cite it consistently.
3. Add eval coverage (`eval-api-version-lifecycle.yaml`) so lifecycle/TypeSpec-required findings are exercised by the automated eval suite and regressions are caught before merge.
## Labels
`ARM API Reviewer agent`
Contributor guide
Research direction
The issue says the work was implemented in PR #45841. Review .github/skills/azure-api-review/references/api-version-lifecycle-and-branches.md, the azure-api-review SKILL.md cross-cutting table, and eval-api-version-lifecycle.yaml; done means the lifecycle guidance, APIVER-* registration, and automated evaluation coverage are present and consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, openapi
- Domain
- api, documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 20/100