Automate website release notes with branch-diffing script

[mattleibow]

Replaces the manual release notes step in the release-publish workflow with an automated system that generates polished website release notes whenever code lands on main, release/* branches, or tags are pushed.

How it works

Workflow trigger → determine branch → invoke release-notes skill → create PR to main

The release-notes skill owns the entire process:

1. Runs generate-release-notes.py --branch {branch} to diff against the predecessor branch
2. Script writes raw PR data with YAML header directly to documentation/docfx/releases/{version}.md
3. AI reads the raw file + TEMPLATE.md, rewrites with polished content
4. TOC and index are regenerated automatically

Branch diffing logic

Branch pushed	Diffs against	Version file	Status
main	Latest release/{minor}.* branch	{SKIASHARP_VERSION}.md	unreleased
release/3.119.x	Latest release/3.119.* versioned branch	3.119.{next}.md	unreleased
release/4.147.0-preview.1	Previous release/4.147.* branch	4.147.0.md	preview
release/3.119.2	release/3.119.2-preview.3 (last preview)	3.119.2.md	stable

Changes

New/rewritten

• generate-release-notes.py — Rewritten from tag-based to branch-diffing. New --branch command with semver-sorted predecessor detection. Writes YAML header + raw PR list directly to the version file. Auto-regenerates TOC/index. Three-state status detection (unreleased/preview/stable).

Updated

• update-release-notes.md workflow — Simplified to 3 steps: determine branch, invoke skill, create PR. No duplicated formatting instructions.
• release-notes/SKILL.md — Skill owns the script. Used both by the workflow and for manual regeneration.
• release-publish/SKILL.md — Removed manual Step 7 (website notes). Tag push triggers the workflow automatically.
• AGENTS.md — Updated command table.

Added

• Polished release notes for 3.119.0, 3.119.1, 3.119.2, 3.119.3, 3.119.4, 4.147.0
• Removed stale 4.133.0.md (never released)

Review feedback incorporated

• Two rounds of Opus 4.7 + GPT-5.4 code reviews
• Fixed: stable tag mapping, 3-state status, servicing off-by-one, fatal fetch, PR failure warnings, tag guard, paths-ignore suppression

 

Automate website release notes with branch-diffing script

Replace manual release-notes generation (release-publish Step 7) with an
automated system. The update-release-notes agentic workflow triggers on
pushes to main, release/*, and v* tags, determines the branch, and
delegates to the release-notes skill.

The skill owns the entire pipeline:
1. generate-release-notes.py --branch diffs against the semver-sorted
   predecessor branch and writes raw PR data with YAML front-matter
   directly to documentation/docfx/releases/{version}.md
2. AI polishes the raw file using TEMPLATE.md
3. TOC.yml and index.md are regenerated automatically

Branch diff logic:
- main: diffs against latest release/{minor}.* branch
- release/X.Y.x: diffs against latest release/X.Y.* versioned branch
- release/X.Y.Z[-preview.N]: diffs against previous branch in semver order

The script emits three-state status (unreleased/preview/stable) so the
AI selects the correct header format. Includes safety checks: fatal on
git fetch failure, warning+abort when >50% of PR fetches fail, refusal
to diff entire history when no release branches exist.

Also adds polished release notes for 3.119.0-3.119.4 and 4.147.0, and
removes stale 4.133.0.md (version was never released).

Co-authored-by: Matthew Leibowitz <mattleibow@live.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[github-actions]

📦 Try the packages from this PR

Warning

Do not run these scripts without first reviewing the code in this PR.

Step 1 — Download the packages

bash / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.sh | bash -s -- 3787

PowerShell / Windows:

iex "& { $(irm https://raw.githubusercontent.com/mono/SkiaSharp/main/scripts/get-skiasharp-pr.ps1) } 3787"

Step 2 — Add the local NuGet source

dotnet nuget add source ~/.skiasharp/hives/pr-3787/packages --name skiasharp-pr-3787

More options

Option	Description
--successful-only / -SuccessfulOnly	Only use successful builds
--force / -Force	Overwrite previously downloaded packages
--list / -List	List available artifacts without downloading
--build-id ID / -BuildId ID	Download from a specific build

Or download manually from Azure Pipelines — look for the nuget artifact on the build for this PR.

Remove the source when you're done:

dotnet nuget remove source skiasharp-pr-3787

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Site
🔗 View Staging Docs
🔗 View Staging Gallery (Blazor)
🔗 View Staging Gallery (Uno Platform)
🔗 View Staging SkiaFiddle

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.