Native Dependency Update Skill

Critical Rules

🛑 STOP AND ASK before: Creating PRs, Merging PRs, Force pushing, Any destructive git operations

🚫 BRANCH PROTECTION (MANDATORY COMPLIANCE)

⛔ POLICY VIOLATION: Direct commits to protected branches are prohibited.

This rule applies to BOTH repositories:

Before ANY commit in either repository:

1. Create a feature branch — Use naming convention: dev/issue-NNNN-description or dev/update-{dep}
2. Never commit directly to main or skiasharp — All changes require a PR
3. This is a compliance requirement — Direct commits bypass review, CI, and audit trails

# ✅ CORRECT — Always create feature branch first
cd externals/skia
git checkout skiasharp
git checkout -b dev/update-libpng
# Now make commits...

# ❌ WRONG — Never do this
cd externals/skia
git checkout skiasharp
git commit -m "Update libpng"  # POLICY VIOLATION

❌ NEVER Do These

Workflow

Phase 1: Discovery

1. Check for existing PRs in mono/SkiaSharp and mono/skia
2. Check current version in externals/skia/DEPS
3. Find target version — get commit hash with git rev-parse {tag}^{commit}

Phase 2: Analysis

Source File Verification (MANDATORY):

cd externals/skia/third_party/externals/{dep}
git diff {old}..{new} --diff-filter=AD --name-only  # Added/Deleted files

Cross-reference against externals/skia/third_party/{dep}/BUILD.gn — new source files may need to be added.

👉 See references/breaking-changes.md for risk assessment.

Phase 3: Local Changes

1. Edit externals/skia/DEPS with new commit hash
2. Update BUILD.gn if needed (rare)
3. Update cgmanifest.json with new version (required for CVE detection)
4. Checkout new version in dependency directory

👉 See documentation/dev/dependencies.md for the cgmanifest format.

Phase 4: Build & Test

🛑 MANDATORY: Build locally before creating PRs.

See documentation/dev/building.md for platform-specific build commands.

dotnet cake --target=externals-macos --arch=arm64  # Example

# Run all tests (core + Vulkan + Direct3D — backends self-skip if unavailable)
dotnet test tests/SkiaSharp.Tests.Console.sln

Phase 5: Create PRs

🛑 STOP AND ASK FOR APPROVAL before creating PRs.

Both PRs must be created together — CI requires both.

Branch Naming Convention

Example: For libfoo, use dev/update-libwebp in both repos.

Step 1: Create mono/skia PR

In the externals/skia directory, create a branch named dev/update-{dep}, commit the DEPS and BUILD.gn changes, push, and create a PR targeting the skiasharp branch.

Step 2: Create SkiaSharp PR

⚠️ CRITICAL: You MUST update the submodule reference, not just cgmanifest.json

In the SkiaSharp root, create a branch named dev/update-{dep}. Then:

1. Update the submodule — In externals/skia, fetch and checkout the branch you just pushed in Step 1
2. Stage both changes — git add externals/skia cgmanifest.json (the submodule AND the manifest)
3. Commit, push, and create a PR targeting main

Step 3: Cross-link the PRs

Edit both PRs to reference each other:

• mono/skia PR → Add: Required SkiaSharp PR: https://github.com/mono/SkiaSharp/pull/{number}
• mono/SkiaSharp PR → Add: Required skia PR: https://github.com/mono/skia/pull/{number}

Phase 5 Completion Checklist

Before proceeding, verify ALL of these:

• Branch names follow dev/update-{dep} convention
• mono/skia PR targets skiasharp branch
• mono/SkiaSharp PR targets main branch
• SkiaSharp's externals/skia submodule points to the mono/skia PR branch (check with git submodule status)
• cgmanifest.json updated with new version
• Both PRs cross-reference each other

Phase 6: Monitor CI

SkiaSharp uses Azure DevOps. mono/skia has no CI — relies on SkiaSharp's.

Phase 7: Merge

🛑 STOP AND ASK FOR APPROVAL before each merge.

🚨 CRITICAL: SQUASH MERGE CREATES NEW COMMITS

When you squash-merge mono/skia PR, GitHub creates a NEW commit SHA on the skiasharp branch. The original commits on dev/update-{dep} become orphaned when the branch is deleted.

If SkiaSharp's submodule still points to the old (orphaned) commit, it will BREAK:

• New clones will fail
• Submodule updates will fail
• Users cannot build SkiaSharp

YOU MUST UPDATE THE SUBMODULE BEFORE MERGING SKIASHARP PR.

Merge Sequence (MANDATORY)

1. Merge mono/skia PR first — This creates a new squashed commit on the skiasharp branch
2. Fetch the updated skiasharp branch and note the new commit SHA
3. Update the SkiaSharp submodule to point to the new squashed commit (not the old branch commit)
4. Push the updated submodule reference to the SkiaSharp PR branch
5. Only then merge the SkiaSharp PR

Merge Checklist

Before proceeding past each step, verify:

• mono/skia PR merged
• Fetched skiasharp branch to get new SHA
• Updated SkiaSharp submodule to new SHA (cd externals/skia && git checkout {new-sha})
• Pushed submodule update to SkiaSharp PR branch
• SkiaSharp PR merged

❌ NEVER merge both PRs in quick succession without updating the submodule in between. ❌ NEVER assume the submodule reference is correct after squash-merging mono/skia.

Phase 8: Verify

• Related issues auto-closed
• Both PRs merged
• No failures on main
• Submodule points to a commit on skiasharp branch — fetch main, check that externals/skia commit exists on origin/skiasharp (not orphaned)

Common Dependencies

For cgmanifest names and upstream URLs, see documentation/dev/dependencies.md.