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

Author: tjprescott

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

@@ -7,6 +7,10 @@ description: Create a GitHub PR for API review by comparing a baseline API surfa
 
 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`.
 
+## 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
 
 1. The user must have `gh` CLI authenticated (`gh auth login`).
@@ -21,11 +25,10 @@ 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:
@@ -38,15 +41,15 @@ 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.
+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. **Confirm the working tree is clean**: Run `git status --porcelain` and warn if there are uncommitted changes.
 
 ## Execution
 
 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
@@ -61,16 +64,11 @@ node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-storag
 node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-cosmos --base azure-cosmos_4.14.0
 ```
 
-**New package (no baseline):**
-```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-keyvault-secrets --target main
-```
-
 ## 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)
 
 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.
 
@@ -100,4 +100,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;
 }
 
@@ -833,28 +837,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 +891,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]);
     }

sdk/template/azure-template/api.md

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