Breaking Changes Checklist for Skia Milestone Updates

How to Use This Document

When updating Skia to a new milestone, follow these steps in order. Each step builds on the previous one. The goal is to identify every change that affects our C API shim layer before you start merging.

Step 1: Gather Release Notes

For each milestone between current and target:

# Fetch and read the official release notes
curl -s https://raw.githubusercontent.com/google/skia/main/RELEASE_NOTES.md | \
  sed -n '/^Milestone {N}$/,/^\* \* \*$/p'

Step 2: Filter by Relevance

SkiaSharp uses Ganesh (not Graphite). Filter changes:

Two common misclassification traps:

1. Shared GPU headers (include/gpu/GpuTypes.h, include/gpu/*.h): Types here are shared across Ganesh and Graphite. Before skipping as "Graphite-only", check if include/gpu/ganesh/ consumes them — e.g., GrFlushInfo uses types from GpuTypes.h.

2. Struct field changes in asserted types: sk_structs.cpp has static_assert(sizeof(...)) for every C API struct mapped via reinterpret_cast. A field addition to any of these C++ structs (encoders, lattice, frame info, etc.) is a build break even if the release notes don't mention it prominently.

Step 3: Categorize Each Change

Create a table for each change:

| # | Change | Risk | C API Impact | C# Impact | Action |
|---|--------|------|-------------|-----------|--------|
| 1 | `GrMipmapped` removed | 🔴 HIGH | sk_types.h enum | GRDefinitions.cs | Update enum + mapping |
| 2 | `SkFont::refTypefaceOrDefault` removed | 🟡 MED | None (not wrapped) | None | No action needed |
| 3 | New `SkVertices::Builder` SK_API | 🟢 LOW | None | None | Optional: wrap later |

Step 4: Verify the Analysis

The release notes don't cover everything. These checks catch what they miss.

Check struct sizes:

# List all asserted structs, then compare each against the target milestone
grep "static_assert.*sizeof" src/c/sk_structs.cpp
git show upstream/chrome/m{TARGET}:include/encode/SkPngEncoder.h | grep -A30 "struct Options"

Check for moved files (Skia relocates, it rarely deletes):

git diff upstream/chrome/m{CURRENT}..upstream/chrome/m{TARGET} --diff-filter=D --name-only
# For each deleted file our C API references:
git ls-tree -r upstream/chrome/m{TARGET} --name-only | grep -i "FILENAME_STEM"

Confirm removals on the target branch (diff - lines can be reorders, not deletions):

# Don't trust the diff — verify directly
git show upstream/chrome/m{TARGET}:include/gpu/ganesh/GrContextOptions.h | grep "fSuppressPrints"

Step 5: C API Impact Analysis

For each HIGH/MEDIUM risk change, check the C API:

cd externals/skia
grep -rn "SYMBOL_NAME" src/c/ include/c/

Recurring patterns across milestone bumps

Step 6: C# Impact Analysis

grep -rn "ENUM_NAME\|FUNCTION_NAME" binding/SkiaSharp/
grep -rn "SYMBOL" binding/SkiaSharp/SkiaApi.generated.cs

Step 7: Build & Verify

After applying fixes:

1. Build native: dotnet cake --target=externals-macos --arch=arm64
2. Regenerate: pwsh ./utils/generate.ps1
3. Build C#: dotnet build binding/SkiaSharp/SkiaSharp.csproj
4. Test: dotnet test tests/SkiaSharp.Tests.Console/SkiaSharp.Tests.Console.csproj

Historical Examples

m132 → m133 Changes Required

Lessons learned:

• SkJSON.h deletion was a relocation to modules/jsonreader/ — always search for moves
• SkPngEncoder::Options field addition broke static_assert — always audit asserted structs
• fSuppressPrints appeared "removed" in diff but was reordered — verify on target branch
• GpuTypes.h changes looked Graphite-only but GrFlushInfo (Ganesh) uses them — trace consumers

m118 → m119 Changes Required

m117 → m118 Changes Required

Risk Assessment Template

Total risk determines approach:

• Low: Direct merge, single iteration
• Medium: Sequential merges recommended
• High: Sequential merges mandatory, extensive testing required