| name | release-branch |
| description | Create a release branch for SkiaSharp. Use when user says "release X", "start release X", "create release branch for X", "I want to release", or "release now". This is the FIRST step of releasing - creates branch and pushes to trigger CI. Can auto-detect next preview version from main branch.
|
Release Branch Skill
Create release branches for SkiaSharp versions.
⚠️ NO UNDO: This is Step 1 of 4 in the release pipeline. See releasing.md for full workflow.
Pipeline: Step 1 (this skill) → Step 2: release-status → Step 3: release-testing → Step 4: release-publish
⚠️ Branch Protection (COMPLIANCE REQUIRED)
🛑 NEVER commit directly to main or skiasharp branches. This is a policy violation.
| Repository | Protected Branches | Required Action |
|---|
| SkiaSharp (parent) | main | Create release/X.Y.Z branch, never commit to main |
| externals/skia (submodule) | main, skiasharp | Must use feature branch if submodule changes needed |
Release branches are created FROM main, but never modify main directly.
Step 1: Determine Version
Auto-detect (user says "release now")
- Fetch main and read
SKIASHARP_VERSION from scripts/azure-templates-variables.yml
- List existing branches:
git branch -r | grep "release/{version}-preview"
- Next preview = highest + 1 (or 1 if none)
- ⚠️ Semver check: Also verify no bare
release/{version} branch exists — if it does, the stable release is already cut and you should NOT create another preview. Ask the user to confirm.
- Confirm with user: "Next release will be
X.Y.Z-preview.N. Proceed?"
User provides version
Use the provided version directly.
Step 2: Determine Release Type
⚠️ Semver ordering: A bare version X.Y.Z is ALWAYS newer than X.Y.Z-preview.N. When listing
branches to find the latest, remember that release/3.119.2 > release/3.119.2-preview.3.
Do NOT use alphabetical sorting — it gives wrong results for semver.
| Version Format | Type | Base | PREVIEW_LABEL |
|---|
X.Y.Z-preview.N | Preview | main | preview.N |
X.Y.Z | Stable | release/X.Y.Z-preview.{latest} | stable |
X.Y.Z.F-preview.N | Hotfix Preview | tag vX.Y.Z | preview.N |
X.Y.Z.F | Hotfix Stable | release/X.Y.Z.F-preview.{latest} | stable |
For stable releases, find latest preview: git branch -r | grep "release/X.Y.Z-preview" | sort -V | tail -1
NuGet version format by release type:
- Preview:
{base}-{PREVIEW_LABEL}.{build} (e.g., 3.119.2-preview.2.3) — build number is part of the prerelease tag
- Stable:
{base} only (e.g., 3.119.2) — the build number is NEVER appended to stable versions. On the internal feed, stable builds appear as {base}-stable.{build} but the published version is just {base}.
Step 3: Create Branch and Update PREVIEW_LABEL
- Checkout the base (main, preview branch, or tag)
- Create branch
release/{version}
- Edit
scripts/azure-templates-variables.yml: set PREVIEW_LABEL
- Commit:
git commit -m "Bump the version to {version}"
- Show diff summary to user and confirm with
ask_user before pushing
Step 4: Push Branch
git push -u origin release/{version}
This triggers the CI pipeline chain (2-4 hours total):
SkiaSharp-Native → SkiaSharp → SkiaSharp-Tests
(~60-90 min) (~30-60 min) (~15-30 min)
Use the release-status skill to track build progress. Quick check:
python3 .agents/skills/release-status/scripts/pipeline-status.py release/{version}
Step 5: Bump Version on Main (Preview from main only)
Skip for stable and hotfix releases.
-
Create branch bump-version-{next} from main
-
Edit scripts/azure-templates-variables.yml:
- Update
SKIASHARP_VERSION to next version
- Reset
PREVIEW_LABEL to preview.0
-
Edit scripts/VERSIONS.txt:
SkiaSharp file → {next}.0- All
SkiaSharp ... nuget lines → {next}
HarfBuzzSharp file → increment 4th digit (e.g., 8.3.1.4 → 8.3.1.5)- All
HarfBuzzSharp ... nuget lines → same as file version
-
Commit: git commit -m "Bump to the next version ({next}) after release"
-
Show diff to user, then:
git push -u origin bump-version-{next}
gh pr create --title "Bump to the next version ({next}) after release" --body ""
gh pr merge --merge --delete-branch
Resources
- releasing.md — Version patterns, HarfBuzz versioning, workflow diagrams
