Release Notes

Release notes — writing the prose

You are writing the human prose for one release-notes page. You do not build the page. A script (release-notes-render.py) owns every heading, table, banner, @handle, ❤️, and PR link. Your entire job is to fill a small set of prose slots, and the renderer assembles the page from those plus the facts in data.json.

The renderer owns headings, handles, contributor lists, and links so those structural elements remain consistent. Focus on turning the activity facts into a changelog a NuGet consumer wants to read.

The one test for everything you write

Would a consumer notice this change without looking inside our repo?

If yes, write about it. If no (CI tweaks, internal refactors, doc/workflow plumbing, test infra), leave it out — the renderer already collapses that noise. data.json tags every PR product / mixed / internal; treat internal as invisible unless it changed shipped behaviour, and for mixed (build config in native/, or a docs API-docs bump) judge from the title.

Running the full pipeline (prepare → write prose → render)

Producing release notes is three steps. Two are scripts you run; the middle one is the writing this skill is about.

prepare.sh   →   (you write prose.json per page)   →   render.sh
 (network)              (this skill)                     (offline)

1. .agents/skills/release-notes/scripts/prepare.sh — regenerates the API diffs (Cake), the per-page _sources/<version>.data.json facts, and _sources/index.json, and writes the list of pages needing prose to output/files-to-polish.txt. When a page's facts changed, Prepare DELETES that page's prose.json so there is nothing stale to keep — every page on the list starts from a blank prose slate.
2. You read each listed page's data.json and write its prose.json from scratch (below). Each page in the list has no prose.json — do not go looking for an old one to "check if it still matches"; the facts moved (new/removed PRs, re-tags), so you author fresh. Cover every product PR you'd expect a consumer to notice — a page that silently drops a real change is the failure this design prevents.
3. .agents/skills/release-notes/scripts/render.sh — renders every page from data.json + prose.json and rebuilds TOC.yml + index.md. It fails loudly if any page on the list still lacks a prose.json (you missed one) or if prose is invalid.

Both scripts take the same three flags — --force, --min-version, --max-version — and nothing else. Choose them from what was asked:

• "regenerate the release notes for 4.151.0" → --min-version 4.151.0 --max-version 4.151.0
• "regenerate the release notes" (everything) → no flags
• after changing the api-diff tools or the page format → add --force (rebuilds even cached api diffs / unchanged pages)

Everything is incremental: an unforced run skips work whose output already exists (a shipped version's api diff never changes), so a routine run is cheap — there is no "notes-only" mode to reach for.

Running locally (needs dotnet, python3, git, gh):

# one version, end to end
.agents/skills/release-notes/scripts/prepare.sh --min-version 4.151.0 --max-version 4.151.0
#   … you write documentation/docfx/releases/_sources/4.151.0.prose.json …
.agents/skills/release-notes/scripts/render.sh  --min-version 4.151.0 --max-version 4.151.0

# everything
.agents/skills/release-notes/scripts/prepare.sh
.agents/skills/release-notes/scripts/render.sh

In CI a separate prepare job runs step 1, and you (the agent) do steps 2 and 3 — write each page's prose, then run release-notes-render.py --all to finalize (the workflow's tool allowlist permits python3 for exactly this).

How to work

You are given a list of pages to write (in CI, output/files-to-polish.txt; one documentation/docfx/releases/<version>.md path per line). The list may be empty — that just means no page needs new prose this run, but you must still run the final render (render.sh, or release-notes-render.py --all in CI) to materialize the deterministic pages and rebuild the TOC/index; don't exit early. Every input for a page lives in a _sources/ folder beside it — for a page releases/<version>.md the inputs are releases/_sources/<version>.data.json, releases/_sources/<version>.prose.json (what you write), and an optional releases/_sources/<version>.notes.md. HarfBuzzSharp is not a separate page — it ships inside each SkiaSharp release, so it renders as a ## HarfBuzzSharp X.Y.Z section on the SkiaSharp page (see harfbuzz_summary below). For each page:

1. Read its _sources/<version>.data.json. It has: prs (title, author, community, tag), previews (each with its PR list), contributors (the authoritative roster), breaking_candidates, tallies, shipments (format 5+; the exact git tag(s) this page rolls up — a preview, an rc, and/or the stable release itself, see release_summaries below), and the banner/link facts.
2. Read every breaking source named in breaking_candidates, if present: the version's *.breaking.md API diffs and every referenced _sources/*.notes.md sidecar. A cumulative page may reference notes from a skipped preview-only line. These are your material for the breaking slot — API diffs give signature removals, while notes sidecars give behavioural breaks (same signature, new runtime behaviour) that no diff can detect.
3. Write documentation/docfx/releases/_sources/<version>.prose.json (schema: scripts/infra/docs/release-notes-schema/prose.schema.json).
4. Render the page: python3 scripts/infra/docs/release-notes-render.py _sources/<version>.data.json _sources/<version>.prose.json <version>.md (use the full documentation/docfx/releases/ paths). If it prints PROSE VALIDATION FAILED, read the errors, fix that slot, and re-run. A clean render — the .md written — is the bar.

You never hand-edit the .md, TOC.yml, or index.md, and you never create, rename, or delete pages — release-notes-render.py --all (which render.sh runs) owns page creation and pruning. The per-page render above is just to validate your prose as you go; render.sh does the authoritative final pass — it re-renders every page and rebuilds TOC.yml + index.md from the committed JSON. Commit the _sources/<version>.prose.json and the rendered .md together (the _sources/<version>.data.json is already produced by the Prepare phase).

The slots

Each slot below lists its purpose, the cap the renderer enforces, and one good + one bad example. Caps are hard: the renderer rejects an over-long highlight, a missing contributor, or an unknown category. Stay well under and you never see an error. Where a slot is nullable or optional, the note says so — reach for null rather than padding.

theme — 2-6 words

What this release is about, shown bold in the banner. No punctuation.

• Good: First stable v4 release
• Bad: Version 4.148.0 (that's the title, not a theme) · Lots of fixes and new APIs (vague)

highlights_headline — one sentence, ≤20 words

The single most important thing about the release. Not a list. Decide it from the product-tagged PRs, the Skia milestone bump, and whether there are breaking changes — the one thing a consumer would care about most, in a sentence. You are not summarising every PR here.

• Good: SkiaSharp 4.148.0 is the first stable v4 release, built on Skia m148.
• Bad: This release adds WebP, SKStream.GetData, singleton lifecycle, pixel fixes, WinUI fixes, and more. (enumeration)

highlights_body — optional, ≤60 words, or null

Name the biggest themes to draw the reader in. Prose is best, but a short feature list is fine for a big release — just keep the whole Highlights block (headline + body) under ~100 words so it stays a lead-in, not the changelog. No PR links, no @handles. If the headline already says enough, use null.

• Good: It adds variable fonts and animated WebP, and reworks the singleton lifecycle. This is a breaking release — check the changes below before upgrading.
• Bad: Includes #4125, #3771, #3772, #4080, #4068 and fixes from @ramezgerges. (links + handles, and it's just PR numbers, not themes)

breaking — array, one entry per change a consumer must act on

Merge from two sources: signature removals in the *.breaking.md diff, and behavioural breaks described in breaking_candidates / the notes sidecar. Empty array is fine and renders "None in this release." Give each a title, a body that says what changed and what to do, and the prs it came from. Only write what you can substantiate: a breaking_candidate carries a hint and sometimes prs, but when its companion file isn't on disk and it lists no concrete change, fall back to the PR titles in prs you can actually read — never invent a removal you can't point at.

• Good: {"title": "SKPaint no longer exposes legacy text state", "body": "The paint text/font members obsoleted in v3 are now compile errors — move typeface and text size onto SKFont.", "prs": [4068, 4114]}
• Bad: {"title": "Refactoring", "body": "Various changes."} (no action, not consumer-facing)

categories — array of {heading, bullets}

The body of the page. heading must be exactly one of these six (the renderer rejects anything else — this is the closed list, in the order they render):

You choose which of the six to include — a section appears only when it has a real product-facing bullet, and you may use as few as one. Prefer fewer, denser sections over many one-bullet ones. Curate, don't enumerate: each bullet MERGES related PRs into one product theme (aim 3-5 bullets per section on a big release; 1-2 is perfectly fine on a servicing release — never merge distinct areas just to hit a count), with a lead (bold summary) + detail (what it means for the consumer) + the prs. The renderer adds the PR links and the ❤️ community credit — never write those yourself. A change with a migration usually belongs in breaking; don't also give it its own thin category section unless it has independent product value. Placement rule of thumb: ordinary fixes go under Bug Fixes even when platform-specific; use Platform only for platform-support additions or removals.

• Good: {"heading": "Bug Fixes", "bullets": [{"lead": "Pixel access corrected", "detail": "GetPixelSpan now uses RowBytes for stride and the right axis for offsets.", "prs": [4148, 4128]}]} (two PRs → one theme)
• Bad: {"heading": "Bugfixes", …} (not one of the six) · one bullet per PR restating its title · a section that lists 20 internal PRs.

contributor_summaries — one line per roster login

data.contributors is authoritative — every login there needs an entry (the renderer fails otherwise) and no one else gets one. Summarise that person's work in prose; the renderer adds their @handle and PR links. This is the one place internal work is worth naming — a contributor's sample or CI work still deserves credit even though it never became a category bullet.

• Good: "ramezgerges": "Singleton lifecycle rework, the SKPath finalizer fix, and Uno sample updates"
• Bad: "ramezgerges": "#4080, #4068, #3796" (that's data, not a summary)

preview_summaries — one line per preview key

data.previews lists each preview/RC with the PRs that first shipped in it. Give each key a 1-2 sentence summary of what that milestone delivered. When a preview only carried internal work, describe the milestone itself (e.g. "opened the line" or "cut the release candidate") rather than forcing a product story.

• Good: "4.148.0-p2": "Preview 2 added animated WebP encoding and the SKPath finalizer fix."
• Bad: leaving a preview key out (the renderer fails), or restating every PR.

harfbuzz_summary — one short paragraph, or null

HarfBuzzSharp ships inside each SkiaSharp release, so its notes are a ## HarfBuzzSharp X.Y.Z section on this page, not a separate page. data.harfbuzz gives the version and prs — the PRs in this release that touched the HarfBuzz binding (a subset of the page's PRs, so you have already written about most of them above). Summarise the HarfBuzz-facing story in 1-2 sentences; the renderer adds the heading, the ❤️ credit and the PR links.

• Required only when data.harfbuzz.prs is non-empty. When it is empty the renderer writes "No HarfBuzzSharp binding changes shipped…" itself — set harfbuzz_summary to null. When data.harfbuzz is absent (e.g. an unreleased head), omit it.
• Good: "Adds variable-font shaping and an HBColor value type, and refreshes the bundled HarfBuzz to 8.3.0."
• Bad: re-listing every PR, or repeating the SkiaSharp highlights verbatim.

release_summaries — optional, one entry per exact shipment tag

This slot writes for a different reader and a different surface than everything above: instead of the website page, it converges the reviewed GitHub Release summary for one exact tag. A separate deterministic updater (scripts/infra/docs/release_notes/update_github_summaries.py) renders each entry into the complete canonical body of that exact tag's GitHub Release. The updater recreates the entire body from the reviewed prose and committed exact-shipment facts: deterministic links, all human contributors, the first-time-human subset, and substantiated automation/AI assistance. It never emits a PR list, preserves old body text, or asks GitHub to generate a live region, so an old generated body is safely replaced rather than preserved. There is no release-critical deadline for it.

The visible body stays short: script-owned shipment label + reviewed headline, optional reviewed body, one compact Release notes/NuGet/Full changelog line, then optional 👥 Contributors, 🎉 First-time contributors, and 🤖 Automation and AI assistance lines. First-timers intentionally appear in both human lines. There is never a What's Changed section or PR bullet list; the website release notes are authoritative for detail.

data.shipments (format 5+, present only on a released page) lists every exact tag this page rolls up — a preview, an rc, and/or the stable release itself — each with its own tag (e.g. "v4.151.0-preview.1.1"), label (e.g. "Preview 1"), and delta prs since the previous tag (globally, not just this page's). Write one release_summaries entry per tag you have enough to say something crisp about; omit a tag entirely rather than pad it — an omitted tag is simply not converged yet, never an error.

Copy each key verbatim from data.shipments; prerelease keys include their exact Arcade build revision.

Each entry is {"headline": string, "body": string|null}:

• headline — one plain-language sentence naming what this exact shipment is about. The updater prefixes it with the shipment's own script-owned label (**Preview 1**) and appends deterministic release-notes/NuGet/changelog links and exact-shipment attribution lines — never write a heading, link, contributor, or @handle yourself.
• body — optional, 1-3 sentences of extra detail; null when the headline says enough.

Both strings go through the release-summary safety gate (scripts/infra/docs/release_notes/safety.py): no code fence, no CVE/security/vulnerability wording (bundled-dependency bumps stay neutral — "Updated libpng to 1.6.44.", never "security fix"), no unwritten placeholder, no heading/list/table as the opening line, and never the literal text of a managed marker. A violation fails the updater loudly rather than shipping — fix the prose in a follow-up PR; it never blocks this one.

• Good: {"headline": "SkiaSharp 4.151.0 previews the Skia m151 engine update.", "body": "It brings the current upstream renderer into the 4.151 line without changing the managed API surface."}
• Bad: {"headline": "Security fix for a bundled library."} (never name security/CVE details) · {"headline": "## What's New"} (that's the renderer's job) · omitting 4.151.0-preview.1 and every other tag just because the stable tag isn't ready yet (converge each tag independently, as its own prose is ready).

Why this is short

There is no separate template, grouping guide, or checklist to reconcile — the renderer is the checklist, and this file is the only instructions. If a rule isn't here, it's because the renderer already guarantees it. Write the prose; let the script build the page.