Python POC for GitHub-based API Reviews (Phase 1)

[Travis Prescott (tjprescott)]

Summary

Adds tooling for GitHub-native API reviews for the Python SDK, enabling API surface tracking and review via GitHub PRs and CI. Based on this proposal: Proposal: API Reviews via GitHub (azure-sdk-tools#15789).

What's Included

1. CI Consistency Check (.github/workflows/api-consistency.yml)

A GitHub Actions workflow that enforces API.md consistency on every PR that touches sdk/**:

1. find_affected.js — diffs the PR against the base branch to find changed packages
2. regenerate.js — runs azpysdk apistub --md --extract-metadata for each affected package
3. find_mismatches.js — compares the regenerated API.md to the committed version and validates select metadata fields
4. Fails with actionable instructions if drift is detected

2. API Review PR Creator (create_api_review_pr.js)

A CLI tool to create dedicated API review PRs:

node scripts/api_md_workflow/create_api_review_pr.js \
  --package-name azure-foo-bar \
  --base azure-foo-bar_1.0.0 \
  --target owner:branch

• Generates API.md for both the base tag and target branch
• Pushes two branches and opens a draft PR where the diff is the API diff
• Reviewers use GitHub's native review tools (comments, suggestions, approvals)

3. Language Adapter Pattern (scripts/api_md_workflow/)

Core orchestration is language-agnostic. A per-repo adapter (adapters/python.js) implements the language-specific logic (isPackageDir, findPackageDir, readVersion, generateApiForPackage). This allows the same framework to be ported to other Azure SDK language repos.

4. Shared Utility Layer (.github/shared/)

Common ESM modules for subprocess execution, logging, path manipulation, and GitHub API interactions — shared across workflow scripts.

Examples

Auto Reviews

• Tag vs main: [API Review] azure-keyvault-keys 4.12.0b3 (base 4.10.0) #47429
• Tag vs tag: [API Review] azure-ai-projects 2.2.0 (base 2.1.0) #47370
• Tag vs main: [API Review] azure-storage-blob 12.31.0b1 (base 12.29.0) #47373

PR Review

• [API Review] azure-cosmos 4.16.0b3 (base 4.14.0) #47439

[Copilot]

Pull request overview

Adds a new repo script (scripts/generate_api_text.py) to generate a package-level API.md by building a wheel, running apiview-stub-generator (apistub) to produce the token JSON, and converting that JSON to markdown via Export-APIViewMarkdown.ps1. This is repo tooling intended to streamline API review artifact generation.

Changes:

• Introduces scripts/generate_api_text.py to locate a package under sdk/*/, build a wheel, run apistub, and emit API.md into the package directory.
• Adds logic to install eng/apiview_reqs.txt and (optionally) upgrade apiview-stub-generator from the Azure SDK package index.
• Uses eng/common/scripts/Export-APIViewMarkdown.ps1 to convert the generated *_python.json token file into markdown.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 30 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• .github/chronus/package-lock.json: Language not supported

[Mike Harder (mikeharder)]

I pruned down the shared code under .github to just the minimum you should currently need