Make review PR creation only work for updates, not new packages.

Author: tjprescott

.github/skills/create-api-review-pr/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: create-api-review-pr
-description: Create a GitHub PR for API review by comparing a baseline API surface against a target branch. Use this when the user wants to create an API review PR, compare API changes between versions, or review API surface differences for a package.
+description: Create a GitHub PR for API review by comparing a baseline API surface against a target tag or branch. Use this when the user wants to create an API review PR, compare API changes between versions, or review API surface differences for a package.
 ---
 
 # Create API Review PR
 
-Creates a dedicated API review PR that shows the diff between a baseline release and a target branch's API surface using `scripts/api_md_workflow/create_api_review_pr.js`.
+Creates a dedicated API review PR that shows the diff between a baseline release and a target tag or branch's API surface using `scripts/api_md_workflow/create_api_review_pr.js`.
+
+## Unsupported Requests
+
+If the user asks to create an API review PR for a new package, explain that new packages do not use API review PRs and stop. Do not gather script inputs or run `create_api_review_pr.js` for new packages.
 
 ## Prerequisites
 
@@ -21,14 +25,14 @@ Ask the user for the following using `vscode_askQuestions`:
 ### 1. Package Name (required)
 The Azure SDK package name (e.g. `azure-storage-blob`, `azure-ai-projects`).
 
-### 2. Baseline (optional)
+### 2. Baseline (required)
 The release tag to use as the baseline for comparison. Tags follow the format `<package-name>_<version>` (e.g. `azure-storage-blob_12.29.0`).
 
 - If the user provides a package name and version separately, construct the tag as `<package-name>_<version>`.
-- If this is a **new package** with no prior release, the baseline should be omitted (the script handles this as an empty baseline).
 
 ### 3. Target (optional)
 The branch or PR to generate the "current" API surface from. Can be:
+- A package release tag (e.g. `azure-storage-blob_12.30.0`) — used directly as a tag ref
 - A branch name (e.g. `main`, `feature-branch`) — fetched from `origin`
 - An `owner:branch` reference (e.g. `someone:their-branch`) — fetched from the fork
 - If omitted, defaults to `origin/main`
@@ -38,15 +42,20 @@ The branch or PR to generate the "current" API surface from. Can be:
 Before running the script:
 
 1. **Validate the package exists**: Confirm a directory matching `sdk/*/<package-name>` exists with a `pyproject.toml` or `setup.py`.
-2. **Validate the baseline tag** (if provided): Run `git tag -l "<tag>"` to confirm the tag exists. If the user provided a version like `12.29.0`, construct the full tag as `<package-name>_<version>` and validate that.
-3. **Confirm the working tree is clean**: Run `git status --porcelain` and warn if there are uncommitted changes.
+2. **Validate the baseline tag**: Run `git tag -l "<tag>"` to confirm the tag exists. If the user provided a version like `12.29.0`, construct the full tag as `<package-name>_<version>` and validate that.
+3. **Validate the target tag when applicable**: If the user provided a target version or tag, construct or validate the full tag as `<package-name>_<version>` and run `git tag -l "<tag>"`.
+4. **Confirm the working tree is clean**: Run `git status --porcelain` and warn if there are uncommitted changes.
 
 ## Execution
 
+This is a long-running operation. The script may take several minutes because it generates API surfaces for both the baseline and target, installs package dependencies, creates or reuses review branches, pushes branches, and then opens the draft PR. Do not treat quiet terminal periods during dependency installation or `apistub` generation as failure unless the command exits, prints an error, or waits for input.
+
+If `create_api_review_pr.js` fails while running this skill, do not patch the script, modify package files, retry with workaround edits, or try to manually complete branch/PR creation. Stop the workflow, report the failure clearly, include the relevant error details, and suggest practical next steps.
+
 Run the following command from the repository root:
 
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name <package-name> [--base <tag>] [--target <target>]
+node scripts/api_md_workflow/create_api_review_pr.js --package-name <package-name> --base <tag> [--target <target>]
 ```
 
 ### Examples
@@ -56,21 +65,25 @@ node scripts/api_md_workflow/create_api_review_pr.js --package-name <package-nam
 node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-storage-blob --base azure-storage-blob_12.29.0 --target someone:feature-branch
 ```
 
-**Review against main (no target specified):**
+**Release-to-release review (comparing two package tags):**
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-cosmos --base azure-cosmos_4.14.0
+node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
 ```
 
-**New package (no baseline):**
+**Review against main (no target specified):**
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-keyvault-secrets --target main
+node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-cosmos --base azure-cosmos_4.14.0
 ```
 
 ## Post-Execution
 
 The script will:
 1. Generate `API.md` for both baseline and target
-2. Push `base_<package>_<version>` and `review_<package>_<version>` branches
+2. Push `apireview/base_<package>_<version>` and `apireview/review_<package>_<version>` branches
 3. Open a draft PR (or print a compare URL if `gh pr create` fails)
 
+During execution, report progress at major phases: baseline generation, target generation, branch creation or reuse, branch push, and PR creation. If the terminal is quiet, check whether the process is still running before assuming it is hung.
+
+When the target is a tag, the PR body labels it as `Target tag`. Branch and fork targets are labeled as `Working branch`.
+
 Report the PR URL to the user when complete.

.github/workflows/src/api-md-consistency/api-md-consistency.js

@@ -44,7 +44,7 @@ function formatIssueSection(title, apiFiles) {
     const packageName = path.basename(packageDir);
     lines.push(`- ${packageDir}`);
     lines.push(`  API file: ${apiFile}`);
-    lines.push(`  Regenerate: azpysdk apistub --md --extract-metadata ${packageName} --dest-dir ${packageDir}`);
+    lines.push(`  Regenerate: azpysdk apistub --md --extract-metadata ${packageName} --dest-dir .`);
   }
   lines.push("");
   return lines.join("\n");

scripts/api_md_workflow/README.md

@@ -22,7 +22,7 @@ It runs on pull requests for changes under `sdk/**`.
 - Regenerates `api.md` for those packages.
 - Fails if the generated files differ from the committed files.
 - Fails if an affected package does not have a committed `api.md`.
-- Prints the mismatched or missing packages and the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir <package-dir>` command needed to regenerate each `api.md` file.
+- Prints the mismatched or missing packages and the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir .` command needed to regenerate each `api.md` file from the repository root.
 
 ## Script Layout
 
@@ -49,7 +49,7 @@ Also writes `count=<n>` to `GITHUB_OUTPUT`.
 
 ### `regenerate.js`
 
-Reads package directories from `API_MD_PACKAGES_FILE` and runs `azpysdk apistub --md --extract-metadata <package-name> --dest-dir <package-dir>` for each package.
+Reads package directories from `API_MD_PACKAGES_FILE` and runs `azpysdk apistub --md --extract-metadata <package-name> --dest-dir <package-dir>` for each package from the repository root.
 
 This script is used by the consistency check.
 
@@ -73,6 +73,14 @@ API review PR creation now uses a shared JavaScript orchestrator with a language
 
 This split allows the core workflow to be reused across other language repos while keeping generation behavior language-specific.
 
+`create_api_review_pr.js` compares a baseline package release tag with a target API surface. The target can be a package release tag, an `origin` branch, or an `owner:branch` fork reference. When the target is a tag, the generated PR body identifies it as a target tag instead of a working branch.
+
+Example comparing two package release tags:
+
+```bash
+node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
+```
+
 ### `api_md_workflow.config.json`
 
 Shared configuration for adapter selection across `api_md_workflow` scripts.
@@ -100,4 +108,4 @@ Common variables include:
 3. `find_affected.js` determines which packages were touched.
 4. `regenerate.js` rebuilds `api.md` for those packages.
 5. `find_mismatches.js` records any `api.md` drift, including missing or untracked `api.md` files.
-6. If drift is found, the workflow fails and prints the affected packages plus the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir <package-dir>` command to regenerate each `api.md` file locally.
+6. If drift is found, the workflow fails and prints the affected packages plus the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir .` command to regenerate each `api.md` file locally from the repository root.

scripts/api_md_workflow/create_api_review_pr.js

@@ -69,6 +69,10 @@ function parseArgs(argv) {
     throw new Error("Missing required --package-name");
   }
 
+  if (!args.base) {
+    throw new Error("Missing required --base");
+  }
+
   return args;
 }
 
@@ -179,19 +183,33 @@ function validateBaseTag(packageName, baseTag) {
   return version;
 }
 
+function resolveTargetTag(target) {
+  if (tagExists(target)) {
+    return target;
+  }
+
+  git(["fetch", REMOTE, "tag", target], { check: false, capture: true });
+  return tagExists(target) ? target : null;
+}
+
 function remoteBranchRef(branch) {
   git(["fetch", REMOTE, branch]);
   return `${REMOTE}/${branch}`;
 }
 
 function resolveTargetRef(target) {
+  const targetTag = resolveTargetTag(target);
+  if (targetTag) {
+    return targetTag;
+  }
+
   if (!target.includes(":")) {
     return remoteBranchRef(target);
   }
 
   const [owner, branch] = target.split(":", 2);
   if (!owner || !branch) {
-    throw new Error(`ERROR: invalid --target '${target}'. Expected either 'branch' or 'owner:branch'.`);
+    throw new Error(`ERROR: invalid --target '${target}'. Expected 'tag', 'branch', or 'owner:branch'.`);
   }
 
   const forkUrl = `https://github.com/${owner}/azure-sdk-for-python.git`;
@@ -765,6 +783,19 @@ function baselineReferenceMarkdown(baseTag) {
   return `[tag \`${baseTag}\`](${commitUrl})`;
 }
 
+function targetReferenceMarkdown(headSelector) {
+  const targetTag = resolveTargetTag(headSelector);
+  if (targetTag) {
+    return baselineReferenceMarkdown(targetTag);
+  }
+
+  return workingReferenceMarkdown(headSelector);
+}
+
+function targetReferenceLabel(headSelector) {
+  return resolveTargetTag(headSelector) ? "Target tag" : "Working branch";
+}
+
 function writeBytes(filePath, bytes) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, bytes);
@@ -812,6 +843,7 @@ async function generateApiBytesForRef({
     return result;
   } finally {
     // Restore the package directory to the current branch state
+    git(["reset", "--", packageRelative], { check: false });
     git(["checkout", "HEAD", "--", packageRelative]);
     // Clean any untracked files that the generation may have left behind
     git(["clean", "-fd", "--", packageRelative], { check: false });
@@ -833,28 +865,22 @@ async function main() {
 
   git(["fetch", REMOTE, "main"]);
 
-  let baseVersion = "none";
-  if (args.base) {
-    baseVersion = validateBaseTag(args.packageName, args.base);
-  }
+  const baseVersion = validateBaseTag(args.packageName, args.base);
 
   const targetRef = args.target ? resolveTargetRef(args.target) : MAIN_REF;
 
   try {
-    let baseResult = null;
-    if (args.base) {
-      logInfo(`\n=== Capturing baseline api.md from tag ${args.base} ===`);
-      baseResult = await generateApiBytesForRef({
-        adapter,
-        repoRoot: REPO_ROOT,
-        packageName: args.packageName,
-        packageDir,
-        runtimeExecutable: args.runtimeExecutable,
-        ref: args.base,
-        refLabel: args.base,
-        logger,
-      });
-    }
+    logInfo(`\n=== Capturing baseline api.md from tag ${args.base} ===`);
+    const baseResult = await generateApiBytesForRef({
+      adapter,
+      repoRoot: REPO_ROOT,
+      packageName: args.packageName,
+      packageDir,
+      runtimeExecutable: args.runtimeExecutable,
+      ref: args.base,
+      refLabel: args.base,
+      logger,
+    });
 
     logInfo(`\n=== Capturing target api.md from ${targetRef} ===`);
     const targetResult = await generateApiBytesForRef({
@@ -893,41 +919,13 @@ async function main() {
     } else {
       logInfo(`\n=== Creating base branch ${baseBranch} ===`);
       git(["checkout", "-B", baseBranch, MAIN_REF]);
-
-      if (baseResult !== null) {
-        writeBytes(apiPath, baseResult.apiMd);
-        git(["add", apiRelative]);
-        if (baseResult.metadata) {
-          writeBytes(metaFilePath, baseResult.metadata);
-          git(["add", metaRelative]);
-        }
-        git(["commit", "-m", `[API Review] Baseline api.md for ${args.packageName} ${baseVersion}`]);
-      } else {
-        const tracked = git(["ls-files", "--error-unmatch", apiRelative], {
-          capture: true,
-          check: false,
-        });
-
-        if (tracked.status === 0) {
-          git(["rm", apiRelative]);
-          const metaTracked = git(["ls-files", "--error-unmatch", metaRelative], {
-            capture: true,
-            check: false,
-          });
-          if (metaTracked.status === 0) {
-            git(["rm", metaRelative]);
-          }
-          git(["commit", "-m", `[API Review] Remove api.md for ${args.packageName} (empty baseline)`]);
-        } else {
-          if (fs.existsSync(apiPath)) {
-            fs.unlinkSync(apiPath);
-          }
-          if (fs.existsSync(metaFilePath)) {
-            fs.unlinkSync(metaFilePath);
-          }
-          git(["commit", "--allow-empty", "-m", `[API Review] Empty baseline for ${args.packageName}`]);
-        }
+      writeBytes(apiPath, baseResult.apiMd);
+      git(["add", apiRelative]);
+      if (baseResult.metadata) {
+        writeBytes(metaFilePath, baseResult.metadata);
+        git(["add", metaRelative]);
       }
+      git(["commit", "-m", `[API Review] Baseline api.md for ${args.packageName} ${baseVersion}`]);
 
       git(["push", "--force-with-lease", REMOTE, baseBranch]);
     }
@@ -975,13 +973,14 @@ async function main() {
 
     const title = `[API Review] ${args.packageName} ${targetVersion} (base ${baseVersion})`;
     const workingSelector = args.target || originalBranch;
-    const workingRef = workingReferenceMarkdown(workingSelector);
+    const workingLabel = targetReferenceLabel(workingSelector);
+    const workingRef = targetReferenceMarkdown(workingSelector);
     const baselineRef = baselineReferenceMarkdown(args.base);
 
     const body = [
       `Automated API review PR for ${args.packageName}.`,
       "",
-      `- **Working branch:** ${workingRef} (version ${targetVersion})`,
+      `- **${workingLabel}:** ${workingRef} (version ${targetVersion})`,
       `- **Baseline:** ${baselineRef} (version ${baseVersion})`,
       "",
       "Generated by scripts/api_md_workflow/create_api_review_pr.js.",

sdk/template/azure-template/api.md

@@ -9,4 +9,4 @@ namespace azure.template.template_code
     def azure.template.template_code.template_main() -> bool: ...
 
 
-```
+```