NPM Release Workflow Skill

NPM Release Workflow

Overview

Standardized release process for cc-devflow npm package ensuring consistent versioning, changelog maintenance, and safe publishing.

Core Principle: Atomic release - all version markers (package.json, CHANGELOG.md, git tag) must stay in sync.

When to Use

Use this skill when:

✅ Ready to release a new version of cc-devflow
✅ All changes committed and pushed
✅ On main branch with clean working directory
✅ Need to publish to npm registry

Don't use when:

❌ Working directory has uncommitted changes
❌ Not on main branch
❌ Pre-release/beta versions (needs adaptation)

Release Types

Follow Semantic Versioning:

| Type | Version Change | When | |------|---------------|------| | Patch | 2.4.3 → 2.4.4 | Bug fixes, minor improvements | | Minor | 2.4.4 → 2.5.0 | New features, backward compatible | | Major | 2.5.0 → 3.0.0 | Breaking changes |

Complete Workflow

Phase 1: Pre-Release Checks

# 1. Verify git status
git status
# MUST show: "On branch main", "working tree clean"

# 2. Check current version
cat package.json | grep version
# e.g., "version": "2.4.3"

# 3. Review recent changes
git log --oneline -10

STOP if:

Not on main branch
Uncommitted changes exist
Unpushed commits exist

Phase 2: Version Updates

Step 1: Update CHANGELOG.md

Add new version section at the top (after ---):

## [X.Y.Z] - YYYY-MM-DD

### 🎯 Release Title

Brief description of main changes.

#### Changed / Added / Fixed
- Bullet point 1
- Bullet point 2

#### Benefits
- ✅ Benefit 1
- ✅ Benefit 2

Step 2: Update package.json

# Manually edit or use npm version
npm version patch --no-git-tag-version  # For patch release
npm version minor --no-git-tag-version  # For minor release
npm version major --no-git-tag-version  # For major release

Or edit directly:

{
  "version": "X.Y.Z"
}

Phase 3: Git Operations

Step 1: Create Release Commit

git add CHANGELOG.md package.json

git commit -m "$(cat <<'EOF'
chore(release): bump version to X.Y.Z

Release X.Y.Z - [Brief title]

主要变更：
- 变更点 1
- 变更点 2

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"

Step 2: Create Annotated Tag

git tag -a vX.Y.Z -m "$(cat <<'EOF'
Release vX.Y.Z - [Brief title]

🎯 Main changes:
- Change 1
- Change 2

Benefits:
✅ Benefit 1
✅ Benefit 2

Full changelog: https://github.com/Dimon94/cc-devflow/blob/main/CHANGELOG.md
EOF
)"

Step 3: Verify

# Check commit
git log --oneline -1

# Check tag
git tag -l "v2.4.*" | tail -3

# Verify tag annotation
git show vX.Y.Z

Phase 4: Publish

Step 1: Push to GitHub

# Push commits
git push origin main

# Push tags
git push origin vX.Y.Z
# Or push all tags: git push origin --tags

Step 2: Create GitHub Release (Optional)

Via GitHub CLI:

gh release create vX.Y.Z \
  --title "vX.Y.Z - [Title]" \
  --notes-file <(sed -n '/## \[X.Y.Z\]/,/## \[/p' CHANGELOG.md | head -n -1)

Or manually at: https://github.com/Dimon94/cc-devflow/releases/new

Step 3: Publish to npm

# Test publish first (dry-run)
npm publish --dry-run

# Actual publish
npm publish

# Verify publication
npm view cc-devflow version

Quick Reference

| Step | Command | Purpose | |------|---------|---------| | Check status | git status | Verify clean state | | Check version | grep version package.json | Current version | | Bump version | Edit package.json | Update version number | | Update changelog | Edit CHANGELOG.md | Document changes | | Create commit | git commit -m "chore(release): ..." | Commit version bump | | Create tag | git tag -a vX.Y.Z -m "..." | Tag release | | Push commits | git push origin main | Push to GitHub | | Push tags | git push origin vX.Y.Z | Push tag to GitHub | | Publish npm | npm publish | Publish to registry |

Common Mistakes

❌ Mistake 1: Forgetting to Update CHANGELOG.md

Problem: Version bumped but no changelog entry

Fix: Always update CHANGELOG.md BEFORE committing

❌ Mistake 2: Inconsistent Version Numbers

Problem: package.json shows 2.4.4 but CHANGELOG.md shows 2.4.3

Fix: Double-check all version numbers match before committing

❌ Mistake 3: Pushing Tag Before Commit

Problem: Tag points to wrong commit

Fix: Always commit first, then tag, then push both together

❌ Mistake 4: Not Testing npm publish

Problem: Published package is broken

Fix: Run npm publish --dry-run first to catch issues

❌ Mistake 5: Network Timeout During Push

Problem: Failed to connect to github.com port 443

Fix:

# Option 1: Retry after network stabilizes
git push origin main
git push origin vX.Y.Z

# Option 2: Switch to SSH (if HTTPS blocked)
git remote set-url origin git@github.com:Dimon94/cc-devflow.git
git push origin main

Network Troubleshooting

If git push fails with timeout:

Check network connectivity:

curl -I https://github.com 2>&1 | head -5

Try SSH instead of HTTPS:

git remote -v  # Check current remote URL
git remote set-url origin git@github.com:Dimon94/cc-devflow.git

If SSH fails (publickey error):
- Check SSH key: ssh -T git@github.com
- Add SSH key to GitHub: https://github.com/settings/keys
- Or stay with HTTPS and retry later
Commits and tags are safe locally:
- They won't be lost
- Push when network is available

Post-Release Verification

After successful release:

# 1. Verify GitHub tag
open https://github.com/Dimon94/cc-devflow/tags

# 2. Verify npm package
npm view cc-devflow version
npm view cc-devflow time

# 3. Test installation
npm install -g cc-devflow@latest
cc-devflow --version  # Should show new version

Rollback (If Needed)

If published version has critical bugs:

# 1. Unpublish from npm (within 72 hours)
npm unpublish cc-devflow@X.Y.Z

# 2. Delete git tag locally and remotely
git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

# 3. Revert commit
git revert HEAD

# 4. Fix bug and re-release with new patch version

Note: npm unpublish is only available within 72 hours of publication. After that, publish a new patch version instead.

Real-World Impact

Following this workflow ensures:

✅ Consistency: All version markers stay in sync
✅ Traceability: Clear changelog and git history
✅ Safety: Dry-run catches issues before publishing
✅ Recoverability: Can rollback if needed
✅ Automation-ready: Scriptable workflow for future CI/CD

[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

Agent Skills: NPM Release Workflow

Install this agent skill to your local

Skill Files