[release-notes] Align rollup boundaries and prerelease links (#5024)

Make release pages and API diffs use stable shipments as cumulative boundaries
while keeping preview-only lines separate, make prerelease banners resolve to
package versions that were actually published, and keep generated Markdown
canonical. Refresh current release artifacts and navigation from these rules.

~~ Stable-delimited rollups ~~

Release notes previously based every versioned page on the preceding stable,
while API diffs normally used the preceding emitted line. Consecutive
preview-only pages therefore repeated earlier work, and a later stable could
not apply one consistent cumulative boundary across both surfaces.

Make preview-only lines compare with the preceding emitted, non-superseded
line. Make stable lines roll every intervening preview-only line into the range
since the preceding non-superseded stable.

Honor an explicit `versions.json` `compare_to` before either default. Require
an exact stable tag, rather than a stable-looking branch name, to establish a
stable boundary; preserve four-segment cores in both Python and Cake; and use
the highest surviving versioned branch when an exact stable branch is absent.

For the current history this produces `4.151.2..4.152.0`,
`4.152.0..4.153.0-preview.1`, and
`4.153.0-preview.1..4.154.0-preview.1`.

~~ Exact prerelease package links ~~

Preview banners synthesized `X.Y.Z-preview` NuGet URLs even when the published
packages used exact build-qualified versions. The 4.152 page consequently
linked to a package that does not exist instead of
`4.152.0-rc.1.26426.14`.

Use the newest exact preview or RC shipment version. Fall back to the newest
preview tag for legacy data, and omit the link when neither exists. Keep the
derived URL prose-independent so refreshed facts preserve reviewed prose.

~~ Canonical generated Markdown ~~

The newly emitted API-diff files exposed an extra blank line at end of file,
which made the staged patch fail Git's whitespace check. Normalize copied
Mono.ApiTools output and new API-diff indexes to exactly one trailing newline.
Preserve existing index endings so a scoped regeneration does not rewrite
historical folders solely for whitespace.

Regenerate release data, prose, Markdown, API diffs, and aggregate navigation.
The 157-test release-notes suite passes; the renderer rebuilt 80 pages, left
the polish queue empty, and rendered prerelease links have no synthetic
numeric `-preview` target.

Co-authored-by: v <v@v.v>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 35401b0a-2541-4d55-855c-0cf93b59a08a

Author: 3 people

documentation/dev/release-notes-and-api-diffs.md

@@ -44,7 +44,7 @@ behavior is to do the same full pipeline and let the engines skip safely.
 - **§1 — The shared versioning model (the rules)**
   - §1.1 One artifact per release *line*, keyed by the version core
   - §1.2 `versions.json` — the only override surface
-  - §1.3 Default comparison: the previous emitted line
+  - §1.3 Default comparison: stable-delimited rollups
   - §1.4 Which lines get an artifact (emission)
   - §1.5 HarfBuzzSharp co-ships inside SkiaSharp pages
 - **§2 — Skill layout & orchestration**
@@ -92,9 +92,10 @@ they diff and the *file layout* they emit (§3).
 
 A **line** is a version with its prerelease label stripped: `4.148.0-rc.1.2` →
 `4.148.0`. Every preview/rc of a line collapses into that line's single artifact,
-named by the **core** (`4.148.0`). The artifact is a **rollup** of everything in the
-line. (The 4th segment of a genuine 4-part *stable* like `1.49.2.1` is preserved;
-only the prerelease suffix is stripped.)
+named by the **core** (`4.148.0`). The artifact includes everything shipped within
+that line, and a stable artifact also rolls up any preview-only lines since the
+preceding stable (§1.3). (The 4th segment of a genuine 4-part *stable* like
+`1.49.2.1` is preserved; only the prerelease suffix is stripped.)
 
 Throughout this doc, the path placeholder **`<line>`** means exactly this version
 core.
@@ -161,33 +162,41 @@ There is intentionally **no** heuristic that infers any of this from git/NuGet.
 release needs special handling, it gets an entry here. Nothing else.
 
 
-### 1.3 Default comparison: the previous emitted line
+### 1.3 Default comparison: stable-delimited rollups
 
-With no `compare_to` override, a line is diffed against **the most recent line before
-it that was itself emitted** (§1.4), **skipping** any `status: "superseded"` line
-(§1.2). Superseded/abandoned lines are therefore transparent: the next emitted line
-diffs past them and rolls their work up.
+With no `compare_to` override, the baseline depends on whether the current line has
+shipped stable:
+
+- A **preview-only line** is diffed against the most recent emitted line before it.
+  Consecutive preview-only lines therefore remain separate instead of repeatedly
+  showing the full delta from the last stable.
+- A **stable line** is diffed against the most recent prior stable line. It therefore
+  rolls up every preview-only line since that stable.
+
+Both searches skip any `status: "superseded"` line (§1.2). Superseded/abandoned
+lines remain transparent and their work is included by the next eligible baseline
+window.
 
 Release notes resolve this rule for **SkiaSharp lines only**. The API-diff engine
 resolves the same rule inside each package-version bucket it emits (`skiasharp` and
 `harfbuzzsharp`), because HarfBuzzSharp API diffs still have their own package version
 scheme (§3.4). There is no HarfBuzzSharp release-notes baseline: its notes are a
 section of the co-shipping SkiaSharp page (§1.5/§4.5).
 
-If there is **no prior emitted line at all** (the first line a bucket ever emits), the
-baseline is **empty**: the API diff is the full public surface and the release notes
-list every PR in the range.
+If there is **no eligible prior line at all** (the first line a bucket ever emits, or
+the first stable in that bucket), the baseline is **empty**: the API diff is the full
+public surface and the release notes list every PR in the range.
 
 Worked examples (today's SkiaSharp versions):
 
-- `4.148.0` → the previous emitted line is the superseded `4.147.0`, which is
-  skipped, so the baseline is the last stable `3.119.4`; `4.148` thus rolls up all of
-  the `4.147` work. (`versions.json` also records `compare_to: "3.119.4"` for it — an
-  explicit belt-and-braces that produces the same result the skip rule would.)
-- `4.150.0` → the previous emitted line is `4.148.0` (a preview-only line ahead of
-  the latest stable still counts as emitted, §1.4), so the baseline is `4.148.0`.
-
-There is no "previous *stable* only" rule and no other heuristic.
+- Preview-only `4.152.0`, `4.153.0`, and `4.154.0` → each line uses the immediately
+  preceding emitted line, so all three artifacts remain separate.
+- If `4.153.0` ships stable while `4.152.0` remains preview-only, `4.153.0` uses the
+  preceding stable as its baseline and rolls up both `4.152.0` and `4.153.0`;
+  preview-only `4.154.0` remains separate.
+- If `4.154.0` is the next stable instead, it rolls up `4.152.0` through `4.154.0`.
+- If `4.152.0` ships stable, later preview-only `4.153.0` and `4.154.0` remain
+  separate until another stable line creates a new rollup boundary.
 
 
 ### 1.4 Which lines get an artifact (emission)
@@ -940,12 +949,13 @@ exist.
 A SkiaSharp version's *released* and *unreleased* states are **orthogonal** and get
 **separate pages** (§3.2) that coexist while the version is in flight:
 
-- **Released `<line>.md`** — the full cumulative **rollup** of a line's shipped
-  prerelease/stable from its baseline (§1.3), carrying preview-milestone sections
-  (§4.3), supersede banners, API-diff links, and (when the co-release map has an entry)
-  the folded HarfBuzzSharp section (§4.5). Its milestones come from the line's `v*`
-  **tags** (§4.1) while the commit range comes from the matching `release/X.Y.Z`
-  **branch** checkout (§4.6) — tags name the previews, the branch supplies the commits.
+- **Released `<line>.md`** — a preview-only line contains its own delta, while a stable
+  line is the cumulative **rollup** since the preceding stable (§1.3). It carries
+  preview-milestone sections (§4.3), supersede banners, API-diff links, and (when the
+  co-release map has an entry) the folded HarfBuzzSharp section (§4.5). Its milestones
+  come from the line's `v*` **tags** (§4.1) while the commit range comes from the
+  matching `release/X.Y.Z` **branch** checkout (§4.6) — tags name the previews, the
+  branch supplies the commits.
 - **Unreleased `<line>-unreleased.md`** — a **small delta** from the **last release on
   that same line** to the head branch (`main`, or a servicing `release/X.Y.x`) —
   "what may ship next". It is **not** a rollup: it ignores `compare_to`, never
@@ -990,7 +1000,8 @@ built from. It is timestamp-free and includes, at minimum:
 
 - `format` (`_DATA_JSON_FORMAT_VERSION`), `version`, `family`, and `status`.
 - `banner`, `supersedes`, `superseded_by`, and `api_links` — all script-owned link /
-  banner facts.
+  banner facts. A preview banner links to the newest exact preview/RC shipment version
+  from `shipments`; it never synthesizes an `X.Y.Z-preview` package URL.
 - `harfbuzz` on released pages — `{ "version", "api_diff_link", "prs" }` for the
   co-shipped HarfBuzzSharp section (§4.5). It is absent on `-unreleased` pages.
 - `prs` — the flat PR map, including title, URL, author, `community`, and the
@@ -1380,9 +1391,10 @@ comparisons:
 - `_data_json_unchanged()` is the genuine no-op check — strict equality, including
   `format`/`shipments`. Only when this is true does an unforced run skip a page
   entirely.
-- `_website_content_unchanged()` ignores `format`/`shipments` — it is true whenever
-  the PRs/roster/previews/links/companions a rendered page and its required prose
-  depend on have not moved, even across a format bump or a shipments-only change.
+- `_website_content_unchanged()` ignores prose-independent metadata — `format`,
+  `shipments`, and the exact preview NuGet URL derived from those shipments. It is
+  true whenever the PRs/roster/previews/links/companions the prose depends on have
+  not moved.
 - `_classify_data_write()` combines the two. A shipments-only change writes the
   refreshed facts, preserves reviewed prose, and does not request another polish
   pass. A website-content change writes the facts, discards stale prose, and

documentation/docfx/releases/1.49.0.md

@@ -1,6 +1,6 @@
 <!-- RELEASE-NOTES DATA (generated, do not edit) format:3 version:1.49.0 -->
 # Version 1.49.0
-> **Initial preview** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/1.49.0-preview)
+> **Initial preview** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/1.49.0-preview1)
 
 ## Highlights
 

documentation/docfx/releases/3.0.0.md

@@ -1,6 +1,6 @@
 <!-- RELEASE-NOTES DATA (generated, do not edit) format:4 version:3.0.0 -->
 # Version 3.0.0
-> **SkiaSharp v3 preview series** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/3.0.0-preview)
+> **SkiaSharp v3 preview series** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/3.0.0-preview.5.4)
 
 > **Superseded by [3.116.0](3.116.0.md)** · Never released as stable — these changes rolled up into 3.116.0.
 

documentation/docfx/releases/3.118.0.md

@@ -1,6 +1,6 @@
 <!-- RELEASE-NOTES DATA (generated, do not edit) format:4 version:3.118.0 -->
 # Version 3.118.0
-> **Skia m117/m118 preview** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/3.118.0-preview)
+> **Skia m117/m118 preview** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/3.118.0-preview.2.3)
 
 > **Superseded by [3.119.0](3.119.0.md)** · Never released as stable — these changes rolled up into 3.119.0.
 

documentation/docfx/releases/3.119.3.md

@@ -1,6 +1,6 @@
 <!-- RELEASE-NOTES DATA (generated, do not edit) format:4 version:3.119.3 -->
 # Version 3.119.3
-> **Security and dependency updates** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/3.119.3-preview)
+> **Security and dependency updates** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/3.119.3-preview.1.1)
 
 > **Superseded by [3.119.4](3.119.4.md)** · Never released as stable — these changes rolled up into 3.119.4.
 

documentation/docfx/releases/4.147.0.md

@@ -1,6 +1,6 @@
 <!-- RELEASE-NOTES DATA (generated, do not edit) format:4 version:4.147.0 -->
 # Version 4.147.0
-> **Opens the v4 line** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/4.147.0-preview)
+> **Opens the v4 line** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/4.147.0-preview.3.1)
 
 > **Superseded by [4.148.0](4.148.0.md)** · Never released as stable — these changes rolled up into 4.148.0.
 

documentation/docfx/releases/4.152.0-unreleased.md

@@ -1,62 +1,61 @@
 <!-- RELEASE-NOTES DATA (generated, do not edit) format:4 version:4.152.0 -->
 # Version 4.152.0
-> **Skia m152, Graphite bindings** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/4.152.0-preview)
+> **Skia m152 and Graphite** · [NuGet (prerelease)](https://www.nuget.org/packages/SkiaSharp/4.152.0-rc.1.26426.14)
 
 > **API changes** · [SkiaSharp API diff](4.152.0/index.md) · [HarfBuzzSharp API diff](harfbuzzsharp/14.2.1.200/index.md)
 
 ## Highlights
 
-SkiaSharp 4.152.0 previews Skia m152 with new Graphite GPU backend bindings and several native leak fixes. It adds a Vulkan.Silk.NET package, backend-neutral async pixel reads, and fixes several use-after-free and undisposed-resource leaks discovered during a memory audit.
+SkiaSharp 4.152.0 previews Skia m152 with Graphite bindings, Vulkan.Silk.NET, and several native lifetime fixes. This preview line adds backend-neutral async pixel reads, restores Nano Server font support, improves package debugging assets, and trims hot-path allocations.
 
 ## Breaking Changes
 
 *None in this preview line.*
 
 ## Engine
 
-- **Skia updated to milestone m152** — Brings the bundled Skia engine up to the m152 upstream release line, plus ongoing chrome/m151 and m152 servicing bug-fix merges. ([#4651](https://github.com/mono/SkiaSharp/pull/4651), [#4538](https://github.com/mono/SkiaSharp/pull/4538), [#4568](https://github.com/mono/SkiaSharp/pull/4568), [#4808](https://github.com/mono/SkiaSharp/pull/4808), [#4537](https://github.com/mono/SkiaSharp/pull/4537))
+- **Skia updated to milestone m152** — Brings the bundled engine onto the m152 upstream line, carries forward the late chrome/m151 fixes, and picks up the subsequent m152 servicing and use-after-free follow-up syncs. ([#4651](https://github.com/mono/SkiaSharp/pull/4651), [#4538](https://github.com/mono/SkiaSharp/pull/4538), [#4568](https://github.com/mono/SkiaSharp/pull/4568), [#4808](https://github.com/mono/SkiaSharp/pull/4808), [#4925](https://github.com/mono/SkiaSharp/pull/4925), [#4537](https://github.com/mono/SkiaSharp/pull/4537))
 
 ## API Surface
 
-- **Graphite GPU backend bindings added** — Adds bindings for Skia's Graphite GPU backend across Vulkan, Metal, and Dawn. — ❤️ [@ramezgerges](https://github.com/ramezgerges) ([#3968](https://github.com/mono/SkiaSharp/pull/3968))
-- **Backend-neutral async pixel reads** — Adds an async RequestReadPixels API to SKImage and SKSurface that works across GPU backends. ([#4545](https://github.com/mono/SkiaSharp/pull/4545))
-- **Vulkan via Silk.NET** — Ships the SkiaSharp.Vulkan.Silk.NET package for applications using Silk.NET to create Vulkan contexts. ([#4527](https://github.com/mono/SkiaSharp/pull/4527), [#4841](https://github.com/mono/SkiaSharp/pull/4841))
+- **Graphite GPU backend bindings added** — Adds managed bindings for Skia's Graphite GPU stack across Vulkan, Metal, and Dawn so early adopters can start integrating the new renderer. — ❤️ [@ramezgerges](https://github.com/ramezgerges) ([#3968](https://github.com/mono/SkiaSharp/pull/3968))
+- **New GPU interop APIs and packages** — Adds backend-neutral async `RequestReadPixels` APIs on `SKImage` and `SKSurface`, and ships the `SkiaSharp.Vulkan.Silk.NET` package for Silk.NET-based Vulkan hosts. ([#4545](https://github.com/mono/SkiaSharp/pull/4545), [#4527](https://github.com/mono/SkiaSharp/pull/4527), [#4841](https://github.com/mono/SkiaSharp/pull/4841))
 
 ## Bug Fixes
 
-- **Native use-after-free and leaks fixed** — Fixes native use-after-free crashes by keeping an SKRegion alive for its SpanIterator and rooting the pixel source of SKPixmap derived views. It also closes leaks in HarfBuzz blob conversion, failed raster-image creation, and SKRuntimeEffectUniforms.Reset(). ([#4355](https://github.com/mono/SkiaSharp/pull/4355), [#4558](https://github.com/mono/SkiaSharp/pull/4558), [#4710](https://github.com/mono/SkiaSharp/pull/4710), [#4455](https://github.com/mono/SkiaSharp/pull/4455), [#4783](https://github.com/mono/SkiaSharp/pull/4783))
-- **Nano Server font support restored** — Uses FreeType for font support on Nano Server. — ❤️ [@jeffska](https://github.com/jeffska) ([#4280](https://github.com/mono/SkiaSharp/pull/4280))
+- **Native lifetime bugs and leaks fixed** — Fixes rooted-lifetime bugs that could trigger use-after-free crashes in `SKRegion.SpanIterator` and `SKPixmap` derived views, and closes leaks in HarfBuzz blob conversion, raster-image failure paths, and `SKRuntimeEffectUniforms.Reset()`. ([#4355](https://github.com/mono/SkiaSharp/pull/4355), [#4558](https://github.com/mono/SkiaSharp/pull/4558), [#4710](https://github.com/mono/SkiaSharp/pull/4710), [#4455](https://github.com/mono/SkiaSharp/pull/4455), [#4783](https://github.com/mono/SkiaSharp/pull/4783))
+- **Nano Server font support restored** — Windows Nano Server packages switch to FreeType for font discovery again, restoring text rendering in constrained server environments. — ❤️ [@jeffska](https://github.com/jeffska) ([#4280](https://github.com/mono/SkiaSharp/pull/4280))
 
 ## Lifecycle & Internals
 
-- **Managed hot paths optimized** — Removes a defensive Feature[] copy in HarfBuzz Font.Shape, avoids char boxing in SKFourByteTag/Tag.ToString, caches a reflection-based skip-registration check, avoids a double buffer copy in SKData.SaveTo, pre-sizes the SKRuntimeEffectUniforms lookup map, and avoids an intermediate string allocation in GetEncodedText's null-terminated path. ([#4690](https://github.com/mono/SkiaSharp/pull/4690), [#4752](https://github.com/mono/SkiaSharp/pull/4752), [#4630](https://github.com/mono/SkiaSharp/pull/4630), [#4550](https://github.com/mono/SkiaSharp/pull/4550), [#4512](https://github.com/mono/SkiaSharp/pull/4512), [#4498](https://github.com/mono/SkiaSharp/pull/4498))
+- **Managed hot paths trimmed** — Removes repeated allocations and reflection overhead from HarfBuzz shaping, tag formatting, `SKData.SaveTo`, text encoding, and runtime-effect uniform lookups so high-frequency calls do less work. ([#4690](https://github.com/mono/SkiaSharp/pull/4690), [#4752](https://github.com/mono/SkiaSharp/pull/4752), [#4630](https://github.com/mono/SkiaSharp/pull/4630), [#4550](https://github.com/mono/SkiaSharp/pull/4550), [#4512](https://github.com/mono/SkiaSharp/pull/4512), [#4498](https://github.com/mono/SkiaSharp/pull/4498))
 
 ## Platform
 
-- **Apple native symbol packages** — Produces symbol packages with native dSYMs for macOS, iOS, Mac Catalyst, and tvOS, improving native debugging without changing the runtime packages. ([#4846](https://github.com/mono/SkiaSharp/pull/4846))
+- **Package docs and symbols improved** — NuGet package READMEs are refreshed, Apple packages now emit dSYM symbol bundles, and Android symbol packages get deterministic identities for more predictable native debugging. ([#4714](https://github.com/mono/SkiaSharp/pull/4714), [#4846](https://github.com/mono/SkiaSharp/pull/4846), [#4843](https://github.com/mono/SkiaSharp/pull/4843))
 
 ## HarfBuzzSharp 14.2.1.200
 
-Avoids a defensive Feature array copy in Font.Shape for lower per-call overhead.
+HarfBuzzSharp 14.2.1.200 reduces per-call shaping overhead in `Font.Shape` and ships with refreshed package metadata and symbol artifacts for easier package consumption and debugging.
 
 ## Community Contributors ❤️
 
 Thank you to everyone who contributed to this release!
 
 | Contributor | Contributions |
 |-------------|---------------|
-| [@jeffska](https://github.com/jeffska) | Restored Nano Server font support by switching it to FreeType. ([#4280](https://github.com/mono/SkiaSharp/pull/4280)) |
-| [@mmitche](https://github.com/mmitche) | Fixed the Windows native build to initialize the MSVC environment only once per build. ([#4570](https://github.com/mono/SkiaSharp/pull/4570)) |
-| [@ramezgerges](https://github.com/ramezgerges) | Added the Graphite GPU backend bindings for Vulkan, Metal, and Dawn. ([#3968](https://github.com/mono/SkiaSharp/pull/3968)) |
+| [@jeffska](https://github.com/jeffska) | Restored Nano Server font support by switching the package set over to FreeType. ([#4280](https://github.com/mono/SkiaSharp/pull/4280)) |
+| [@mmitche](https://github.com/mmitche) | Simplified Windows native builds by initializing the MSVC environment once per build. ([#4570](https://github.com/mono/SkiaSharp/pull/4570)) |
+| [@ramezgerges](https://github.com/ramezgerges) | Added Graphite GPU backend bindings for Vulkan, Metal, and Dawn. ([#3968](https://github.com/mono/SkiaSharp/pull/3968)) |
 
 ## Release Candidate 1 (August 26, 2026)
 
-Release Candidate 1 bumped to Skia m152, restored Vulkan.Silk.NET package production, added Apple native symbol packages, and fixed additional resource leaks.
+Release Candidate 1 refreshed the bundled m152 engine, restored Vulkan.Silk.NET package production, improved symbol packaging, and fixed more resource leaks ahead of stable release.
 
 [Full changelog](https://github.com/mono/SkiaSharp/compare/v4.152.0-preview.1.1...v4.152.0-rc.1.26426.14)
 
 ## Preview 1 (August 5, 2026)
 
-Preview 1 added the Graphite GPU backend bindings, the Vulkan.Silk.NET package, backend-neutral async pixel reads, and fixed several native memory leaks found during an audit.
+Preview 1 opened the m152 line with Graphite bindings, the Vulkan.Silk.NET package, backend-neutral async pixel reads, Nano Server font support, and several native lifetime fixes.
 
 [Full changelog](https://github.com/mono/SkiaSharp/compare/v4.151.2...v4.152.0-preview.1.1)