Azure / Azure/azure-rest-api-specs

ARM API Reviewer agent: add API version lifecycle, branch placement, promotion, TypeSpec conversion, and date-ordering guidance

Open
#45,945 0 comments 0 reactions 0 assignees View on GitHub
ARM API Reviewer agent
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.