release

name	release
description	Create a new version release with git tag and GitHub Release. Use when user asks to release, publish, create a new version, or ship a release. (project)

Release Skill

Create a new version release using prefixed tag-based workflow for monorepo plugins.

When to Use

• User explicitly asks to "release" or "create a release"
• User asks to "publish" or "ship" a new version
• User asks to "tag" a version
• User says "let's release v0.2.0" or similar

Plugin Identification

This is a monorepo with multiple plugins. First, identify which plugin to release:

Plugin	Version File	Tag Format	Example
Stash Downloader	plugins/stash-downloader/package.json	downloader-vX.Y.Z	downloader-v0.5.2
Stash Browser	plugins/stash-browser/package.json	browser-vX.Y.Z	browser-v0.1.0

If the user doesn't specify, ask which plugin to release. If both changed, release each separately.

Pre-Release Checklist

Before creating a release, verify:

1. On dev branch: git branch --show-current
2. No uncommitted changes: git status
3. Type-check passes: npm run type-check
4. Lint passes: npm run lint
5. Tests pass: npm test -- --run
6. Build succeeds: npm run build

Release Process (Tag-Based)

Step 1: Determine Version Bump

1. Check current version: Read the plugin's package.json version field
2. Review commits since last tag: git log $(git describe --tags --match "downloader-v*" --abbrev=0)..HEAD --oneline (or browser-v* for Browser)
3. Determine bump type:

Commit Types	Bump	Example
Breaking changes (feat!:, BREAKING CHANGE)	MAJOR	0.1.0 → 1.0.0
New features (feat:)	MINOR	0.1.0 → 0.2.0
Bug fixes, patches (fix:, docs:, chore:)	PATCH	0.1.0 → 0.1.1

Step 2: Merge dev to main and Release

For Stash Downloader:

# From dev branch, checkout main and merge
git checkout main
git merge dev

# Update version in plugin's package.json
cd plugins/stash-downloader
npm version patch  # or minor/major

# Commit the version bump
git add .
git commit -m "$(cat <<'COMMIT'
🔖 chore: release downloader-vX.Y.Z

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>
COMMIT
)"

# Create and push tag (with downloader- prefix!)
git tag downloader-vX.Y.Z
git push origin main --tags

For Stash Browser:

# From dev branch, checkout main and merge
git checkout main
git merge dev

# Update version in plugin's package.json
cd plugins/stash-browser
npm version patch  # or minor/major

# Commit the version bump
git add .
git commit -m "$(cat <<'COMMIT'
🔖 chore: release browser-vX.Y.Z

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>
COMMIT
)"

# Create and push tag (with browser- prefix!)
git tag browser-vX.Y.Z
git push origin main --tags

Step 3: Wait and Sync Dev

⚠️ CRITICAL: Do NOT push to dev immediately!

GitHub Pages uses a concurrency group. If you push to dev before the stable workflow finishes, the stable deploy gets CANCELLED.

# 1. Wait for workflow to complete
#    Check: https://github.com/Codename-11/Stash-Downloader/actions

# 2. AFTER workflow completes, sync dev with main
git checkout dev
git merge main
git push origin dev

What Happens After Tag Push

GitHub Actions automatically:

1. Runs CI (type-check, lint, tests)
2. Builds the plugin
3. Updates GitHub Pages (Stash plugin index)
4. Generates AI release notes (if GOOGLE_API_KEY configured)
5. Creates GitHub Release with:
   • Auto-generated changelog
   • Installation instructions
   • ZIP file attached

If Release Was Cancelled

If you accidentally pushed to dev too early and cancelled the stable deploy:

# Re-push the tag to trigger the workflow again
git push origin --delete downloader-vX.Y.Z  # or browser-vX.Y.Z
git push origin downloader-vX.Y.Z

PR-Based Release (Optional)

For significant releases where you want Claude review before merging:

# Create release branch from dev
git checkout -b release/downloader-vX.Y.Z dev

# Update version in plugin's package.json, commit
cd plugins/stash-downloader
npm version patch
git add .
git commit -m "🔖 chore: release downloader-vX.Y.Z"

# Push and create PR to main
git push -u origin release/downloader-vX.Y.Z
gh pr create --base main --title "🔖 Release downloader-vX.Y.Z" --body "Release notes..."

# After PR merge, checkout main and tag
git checkout main
git pull origin main
git tag downloader-vX.Y.Z
git push origin downloader-vX.Y.Z

Important Notes

• Tag format MUST include plugin prefix: downloader-vX.Y.Z or browser-vX.Y.Z
• Version in the plugin's package.json must match tag version (without prefix)
• Always start from dev branch - never commit directly to main
• Wait for workflow to complete before syncing dev
• Push to main without a tag triggers NOTHING
• Verify release succeeded in GitHub Actions after pushing tag
• Release plugins separately - if both plugins changed, create separate tags