Make doc generation reproducible and Linux-only; unify "API diff" terminology

.agents/skills/release-notes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: release-notes
 description: >
-  Generate or regenerate SkiaSharp's website release notes AND API changelogs as one
+  Generate or regenerate SkiaSharp's website release notes AND API diffs as one
   coherent set under documentation/docfx/releases/. Two phases: (1) Prepare — one script
   (scripts/generate.sh) regenerates everything deterministic (the API-diff tree +
   co-release-map sidecar from the published NuGet feed, and each version page's raw-data
@@ -10,13 +10,13 @@ description: >
 
   Use this skill whenever the user asks to:
   - Generate or regenerate release notes for a version ("write release notes for 3.119.2")
-  - Regenerate or refresh the API changelogs / API diff ("update the api diff", "regen changelogs")
+  - Regenerate or refresh the API diffs ("update the api diff", "regen the api diffs")
   - Refresh the whole releases/ set after publishing packages
   - Manually fix or update release notes that the automated workflow got wrong
 
-  Triggers: "release notes for X", "regenerate release notes", "update API changelogs",
-  "api diff", "changelog", "update website release notes", "write release notes",
-  "refresh release notes".
+  Triggers: "release notes for X", "regenerate release notes", "update API diffs",
+  "api diff", "update website release notes", "write release notes",
+  "refresh release notes". Also matches the legacy term "changelog" / "API changelog".
 
     NOTE: The full set is normally regenerated automatically by the `update-release-notes`
   agentic workflow when code lands on main, release branches, or tags are pushed. In that
@@ -26,9 +26,9 @@ description: >
   in `output/files-to-polish.txt`.
 ---
 
-# Release Notes & API Changelogs Skill
+# Release Notes & API Diffs Skill
 
-Generate SkiaSharp's website release notes **and** API changelogs as one coherent set.
+Generate SkiaSharp's website release notes **and** API diffs as one coherent set.
 
 This skill is used both by the `update-release-notes` agentic workflow (automatically
 on push to `main`, `release/*` branches, and tags) and manually when regenerating,
@@ -87,8 +87,8 @@ The flags narrow what it touches:
 
 | Invocation | What it regenerates |
 | --- | --- |
-| `generate.sh` (no args) | **Both** — the API changelogs **and** the release-notes pages, for every branch. *(The default, and what the workflow uses.)* |
-| `generate.sh --api-only` | Only the machine-generated **API-diff changelog** tree under `documentation/docfx/releases/`. |
+| `generate.sh` (no args) | **Both** — the API diffs **and** the release-notes pages, for every branch. *(The default, and what the workflow uses.)* |
+| `generate.sh --api-only` | Only the machine-generated **API-diff** tree under `documentation/docfx/releases/`. |
 | `generate.sh --notes-only` | Only the release-notes **pages'** raw-data blocks (+ `TOC.yml`/`index.md`). |
 | `generate.sh <scope args>` | Same as default but limited to the given scope, e.g. `--branch main`, `--branch release/4.147.0-preview.1`, or a version like `3.119.2`. |
 
@@ -256,7 +256,7 @@ Follow these rules:
 
 9. **Rollup at top** — Aggregate ALL changes across all previews into the main sections.
 
-10. **Previews are minimal** — One sentence + changelog link each, at the bottom.
+10. **Previews are minimal** — One sentence + Full Changelog link each, at the bottom.
     Render one trailing `## <label> (<date>)` section per entry in the data-block's
     `preview milestones` list (newest first), using that entry's compare link. Do not invent
     previews or dates — the list is authoritative (sourced from published prerelease tags).

.agents/skills/release-notes/scripts/generate.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 #
 # generate.sh — the Prepare phase: run the two deterministic
-# release-notes/changelog generators in the required order (Cake -> Python),
+# release-notes/api diff generators in the required order (Cake -> Python),
 # VERBOSE, and write the "Files to polish" list to a file.
 #
 # Output contract (spec §2.2/§2.3): this script is VERBOSE. Cake and Python
@@ -22,9 +22,9 @@
 #   generate.sh [--api-only | --notes-only] [--polish-list <path>] \
 #               [extra args for the Python script...]
 #
-#   (no scope args)      Full regeneration of everything: API changelogs (Cake)
+#   (no scope args)      Full regeneration of everything: API diffs (Cake)
 #                        then release-notes raw data for every branch (Python --all).
-#   --api-only           Run only the Cake API-changelog generator.
+#   --api-only           Run only the Cake API-diff generator.
 #   --notes-only         Run only the Python release-notes generator.
 #   --polish-list <path> Forwarded to the Python generator: write the "Files to
 #                        polish" list to <path> instead of the default
@@ -42,6 +42,13 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel)"
 
+# The two generation paths each have a single canonical script under
+# scripts/infra/docs/ that local runs, CI, and the docs Docker wrapper all share. This
+# orchestrator just calls them in the required order (Path 1 api diffs -> Path 2
+# notes); it owns no commands of its own so nothing can drift between here and CI.
+API_DIFFS_SH="$REPO_ROOT/scripts/infra/docs/generate-api-diffs.sh"
+RELEASE_NOTES_SH="$REPO_ROOT/scripts/infra/docs/generate-release-notes.sh"
+
 run_api=1
 run_notes=1
 polish_list=""
@@ -66,27 +73,16 @@ fi
 cd "$REPO_ROOT"
 
 if [ "$run_api" = 1 ]; then
-  if ! command -v dotnet >/dev/null 2>&1; then
-    echo "ERROR: the .NET SDK ('dotnet') is required for the API-changelog generator but was not found." >&2
-    echo "       Install the SDK pinned in global.json and retry, or pass --notes-only to skip it." >&2
-    exit 1
-  fi
-  echo "==> Prepare [1/2]: API changelogs (Cake: docs-api-diff-past) — verbose"
-  dotnet tool restore
-  dotnet cake --target=docs-api-diff-past --nugetDiffPrerelease=true
+  echo "==> Prepare [1/2]: API diffs (Path 1) — verbose"
+  "$API_DIFFS_SH"
 fi
 
 if [ "$run_notes" = 1 ]; then
-  if ! command -v python3 >/dev/null 2>&1; then
-    echo "ERROR: 'python3' is required for the release-notes generator but was not found." >&2
-    echo "       Install Python 3 and retry, or pass --api-only to skip it." >&2
-    exit 1
-  fi
   py_args=("${notes_args[@]}")
   if [ -n "$polish_list" ]; then
     py_args+=(--polish-list "$polish_list")
     echo "==> Files-to-polish list -> $polish_list"
   fi
-  echo "==> Prepare [2/2]: release-notes raw data (generate-release-notes.py ${py_args[*]}) — verbose"
-  python3 "$SCRIPT_DIR/generate-release-notes.py" "${py_args[@]}"
+  echo "==> Prepare [2/2]: release-notes raw data (Path 2) — verbose"
+  "$RELEASE_NOTES_SH" "${py_args[@]}"
 fi