_setup: build only versions added by a package/<pkg> PR

.github/workflows/_setup.yml

@@ -43,7 +43,22 @@ jobs:
         env:
           PACKAGE: ${{ inputs.package }}
           VERSION_GLOB: ${{ inputs.version }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_REF: ${{ github.base_ref }}
         run: |
-          versions=$(uv run --quiet ci_scripts/pending_versions.py ${VERSION_GLOB:+--glob "$VERSION_GLOB"} "$PACKAGE")
+          args=()
+          if [ -n "$VERSION_GLOB" ]; then
+            args+=(--glob "$VERSION_GLOB")
+          elif [[ "$HEAD_REF" == package/* ]]; then
+            # A package/<pkg> PR builds only the versions it adds on top of the
+            # base branch. Versions already merged there but not yet released
+            # stay pending in the YAML; the commit that links a release must not
+            # rebuild them.
+            git fetch --quiet --depth=1 origin "$BASE_REF"
+            git show "FETCH_HEAD:docs/packages/$PACKAGE.yaml" > "$RUNNER_TEMP/base.yaml" 2>/dev/null \
+              || : > "$RUNNER_TEMP/base.yaml"
+            args+=(--base-file "$RUNNER_TEMP/base.yaml")
+          fi
+          versions=$(uv run --quiet ci_scripts/pending_versions.py "${args[@]}" "$PACKAGE")
           echo "versions=$versions" >> "$GITHUB_OUTPUT"
           echo "Versions to build: $versions"

ci_scripts/pending_versions.py

@@ -13,6 +13,10 @@
 pending; with no --glob, those are the versions returned. With --glob, every
 version matching the glob is returned, released or not, so a workflow_dispatch
 can force a rebuild.
+
+With --base-file, versions that the given (base branch) copy of the package
+YAML already declares are left out, so a pull request only builds the versions
+it adds.  An empty or missing base file means every version is new.
 """
 
 import argparse
@@ -65,6 +69,13 @@ def select_versions(versions, glob=None):
     return [str(v["version"]) for v in versions if is_pending(v)]
 
 
+def base_versions(path):
+    """Versions declared in the base branch's copy of the package YAML."""
+    text = Path(path).read_text() if Path(path).exists() else ""
+    data = yaml.safe_load(text) or {}
+    return {str(v["version"]).strip() for v in data.get("versions") or []}
+
+
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("package", help="docs/packages/<package>.yaml to read")
@@ -73,6 +84,10 @@ def main():
         default="",
         help="version glob to build, released or not (default: pending versions only)",
     )
+    parser.add_argument(
+        "--base-file",
+        help="base branch copy of the package YAML; skip versions it declares",
+    )
     parser.add_argument(
         "--check",
         action="store_true",
@@ -84,6 +99,10 @@ def main():
     if args.check:
         return
 
+    if args.base_file and not args.glob:
+        already_on_base = base_versions(args.base_file)
+        versions = [v for v in versions if str(v["version"]) not in already_on_base]
+
     selected = select_versions(versions, args.glob)
     if args.glob and not selected:
         raise SystemExit(

docs/workflows.md

@@ -118,7 +118,10 @@ setup:
 `_setup.yml` runs `ci_scripts/pending_versions.py` and returns a JSON version
 list:
 
-- without a dispatch glob, every pending version is returned;
+- without a dispatch glob, every pending version is returned, except that on a
+  pull request from a `package/<pkg>` branch only the versions the PR adds to
+  `docs/packages/<pkg>.yaml` on top of the base branch are returned, so linking
+  a release does not rebuild versions already merged but not yet released;
 - with a dispatch glob, every matching declared version is returned, including
   versions already released;
 - if nothing is pending, it returns `[]`.