Release Publish Skill

Workflow Overview

┌────────────────────────────────────────────────────────────────────┐
│  1. Confirm Versions     → Verify packages exist on preview feed   │
│  2. Publish to NuGet.org → Trigger Azure pipeline (manual)         │
│  3. Verify Published     → Poll NuGet.org until indexed            │
│  4. Tag Release          → Push git tag (ask_user first!)          │
│  5. Create GitHub Release→ Generate notes, set prerelease flag     │
│  6. Annotate Notes       → Add platform/contributor emojis         │
│  7. Close Milestone      → Stable releases only                    │
└────────────────────────────────────────────────────────────────────┘

Preview vs Stable differences:

Step 1: Confirm Versions

⚠️ Semver Version Ordering

When identifying which version to publish, use semver ordering, not alphabetical:

• 3.119.2 (bare) is NEWER than 3.119.2-preview.3 — it's the stable/final release
• Always verify you are publishing from the correct branch
• If both release/3.119.2 and release/3.119.2-preview.3 exist, the bare version is the latest

Prerequisite: release-testing must have passed. Versions should be known from testing.

The user should provide:

• Preview: SkiaSharp version with build number (e.g., 3.119.2-preview.2.3)
• Stable: SkiaSharp base version only (e.g., 3.119.2) — no build number

⚠️ Stable versions never include a build number. The build number only appears in the prerelease component (e.g., 3.119.2-preview.2.3) or in the internal stable tag (e.g., 3.119.2-stable.3). It is never appended to the base version directly.

If not provided, ask for them using ask_user.

Quick verification — confirm packages exist on preview feed:

# Preview: search for the exact NuGet version
dotnet package search SkiaSharp --source "https://aka.ms/skiasharp-eap/index.json" --exact-match --prerelease --format json | jq -r '.searchResult[].packages[].version' | grep "{expected-version}"

# Stable: search for internal stable builds (NuGet version is just the base, e.g., 3.119.2)
dotnet package search SkiaSharp --source "https://aka.ms/skiasharp-eap/index.json" --exact-match --prerelease --format json | jq -r '.searchResult[].packages[].version' | grep "^{base}-stable\."

If missing, STOP and ask user to verify testing was completed.

Step 2: Publish to NuGet.org

Trigger the publish pipeline to push packages to NuGet.org.

Pipeline Steps

1. Open the NuGet.org publish pipeline
2. Click "Run pipeline"
3. Select "SkiaSharp" from the radio buttons
4. Check "Confirm push to NuGet.org" checkbox
5. For stable releases ONLY: Check "Push stable packages" checkbox
   • ⚠️ Do NOT check this for preview releases
6. Click "Next: Resources"
7. In "Pipeline artifacts", click the SkiaSharp artifact selector
8. From the branch dropdown, select release/{version} (the release branch)
9. From the pipeline runs list, select the correct build by checking the build number
10. Click "Use selected run"
11. Click "Run"

Verification During Pipeline Run

⚠️ Before approving the push step, verify BOTH:

1. Run name — The pipeline run will rename itself to the version being released. Confirm this matches your expected version.
2. Push type — The publish step will indicate "Push Preview" or "Push Stable". Verify this matches your release type:
   • Preview release → should show "Push Preview"
   • Stable release → should show "Push Stable"

Only approve the push step when both are correct. Wait for pipeline completion (typically 5-10 minutes after approval).

Ask user to follow these steps and wait for completion.

Step 3: Verify Packages Published

Use curl to verify (more reliable than dotnet package search which has version limits):

# Check if packages exist - HTTP 200 = success
curl -s -o /dev/null -w "%{http_code}" "https://api.nuget.org/v3-flatcontainer/skiasharp/{version}/skiasharp.nuspec"
curl -s -o /dev/null -w "%{http_code}" "https://api.nuget.org/v3-flatcontainer/harfbuzzsharp/{version}/harfbuzzsharp.nuspec"

If packages not yet indexed, poll until available (NuGet.org can take 5-15 minutes):

# Poll every 30 seconds, max 10 minutes
for i in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
  skia=$(curl -s -o /dev/null -w "%{http_code}" "https://api.nuget.org/v3-flatcontainer/skiasharp/{version}/skiasharp.nuspec")
  hb=$(curl -s -o /dev/null -w "%{http_code}" "https://api.nuget.org/v3-flatcontainer/harfbuzzsharp/{version}/harfbuzzsharp.nuspec")
  echo "$(date +%H:%M:%S) - SkiaSharp: $skia, HarfBuzzSharp: $hb"
  if [ "$skia" = "200" ] && [ "$hb" = "200" ]; then
    echo "✅ Both packages available on NuGet.org!"
    break
  fi
  sleep 30
done

Note: Use explicit list 1 2 3... instead of {1..20} brace expansion for better compatibility with async shell execution.

Or manually check: https://www.nuget.org/packages/SkiaSharp/{version}

Step 4: Tag Release

Tag formats:

• Preview: vX.Y.Z-preview.N.{build} (e.g., v3.119.2-preview.2.5)
• Stable: vX.Y.Z (e.g., v3.119.2)

git fetch origin
git checkout release/{branch-version}
git pull
git tag {tag}

Confirm with ask_user before pushing tag (cannot be undone):

git push origin {tag}

Step 5: Create GitHub Release

Title Format

Finding the Previous Release Tag

Always use --notes-start-tag to explicitly specify the previous release. The auto-selection may pick the wrong tag.

# List recent tags to find the previous release
git tag -l "v3.119*" --sort=-v:refname | head -10

Commands

# Preview (e.g., v3.119.2-preview.2.3)
gh release create {tag} \
  --title "Version {X.Y.Z} (Preview {N})" \
  --generate-notes \
  --notes-start-tag {previous-tag} \
  --prerelease \
  --verify-tag

# Stable (e.g., v3.119.2)
gh release create {tag} \
  --title "Version {X.Y.Z}" \
  --generate-notes \
  --notes-start-tag {previous-tag} \
  --verify-tag

# Upload samples for stable releases (if available)
gh release upload {tag} samples.zip

• --title sets the release title (use format above)
• --generate-notes auto-generates release notes from PRs/commits
• --notes-start-tag specifies the previous release to diff from (required)
• --prerelease marks as prerelease (preview only)
• --verify-tag ensures the tag exists before creating the release

Step 6: Annotate Release Notes with Emojis

After creating the release, annotate each PR line with platform and community emojis.

👉 See references/release-notes.md for:

• Complete emoji reference (platform + contributor)
• Label-to-platform mapping
• Title keyword detection
• Full annotation process and examples

Quick summary:

1. Get release body: gh release view {tag} --json body -q '.body' > /tmp/skiasharp/release/release-body.md
2. For each PR: determine platform emoji, add ❤️ for non-mattleibow contributors
3. Build sections: Breaking Changes (if any), New Features (if any), What's Changed (all)
4. Update release: gh release edit {tag} --notes-file /tmp/skiasharp/release/release-body.md

Step 7: Close Milestone (Stable only)

Skip for preview releases.

gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number): \(.title)"'
gh api repos/:owner/:repo/milestones/{number} -X PATCH -f state=closed

Error Recovery

Pipeline Fails

NuGet.org Issues

Git/GitHub Issues

General Recovery

If you've partially completed and need to resume:

1. Check what's done: gh release view {tag} (release exists?), git ls-remote --tags origin (tag exists?)
2. Skip completed steps
3. Continue from where you left off

Resources

• releasing.md — Version patterns, tag formats, workflow diagrams
• references/release-notes.md — Emoji annotation details