DEV Community

Jeremy Longshore
Jeremy Longshore

Posted on • Originally published at startaitools.com

Production Release Engineering: Shipping v4.5.0 with 739 Skills and Zero Downtime

#releaseengineering #automation #devops #versioncontrol

The Challenge

I needed to ship v4.5.0 of the Claude Code Plugins marketplace after 8 days of intensive development. The release included:

  • 38 commits across multiple feature areas
  • 500 new standalone skills (739 total)
  • ZCF Integration (5 phases complete)
  • External Plugin Sync infrastructure
  • MCP Registry manifests for 7 servers
  • 5,385 files changed (+197K lines, -8K lines)

The requirement: Zero manual errors, complete audit trail, automated quality gates, and the ability to roll back at any failure point.

Why This Matters

Most teams ship releases manually:

  • Someone updates version numbers in 3-4 files
  • Another person writes changelog entries
  • A third verifies tests pass
  • Someone tags the commit
  • Another creates the GitHub release

The problems:

  1. Version conflicts between files
  2. Changelog drift from actual changes
  3. Manual processes = human errors
  4. No rollback automation
  5. Poor audit trails

I wanted to prove you can automate ALL of it with intelligent analysis and safety gates.

The Journey: Building Universal Release Engineering

First Attempt: Manual Release Process

Initially, I'd run releases like everyone else:

# Update package.json manually
vim package.json  # Change 4.4.0 → 4.5.0

# Update README manually
vim README.md     # Update badges

# Write changelog manually
vim CHANGELOG.md  # Summarize 38 commits from memory

# Create release
git add -A
git commit -m "chore: release v4.5.0"
git tag v4.5.0
git push origin main --tags
Enter fullscreen mode Exit fullscreen mode

The problem I hit: After shipping v4.3.0, I realized:

  • README said v4.3.0
  • package.json said v4.2.9
  • CHANGELOG was missing 12 commits

Version conflicts everywhere. No single source of truth.

Second Attempt: Config-Driven Release Automation

I built a /release skill that would:

  1. Detect version scheme (semver vs padded)
  2. Find ALL version files automatically
  3. Analyze commits to determine bump level
  4. Generate changelog from git history
  5. Update all files atomically
  6. Create tag and GitHub release

The architecture:

Preflight Checks → Analysis → Decision → Plan → Apply → Verify
     ↓                ↓          ↓         ↓       ↓       ↓
  Working tree    Git log   Bump level  File     Commit  GitHub
  is clean?       parsing   (semver)    updates  + tag   release
Enter fullscreen mode Exit fullscreen mode

Each phase is a gate - if it fails, the entire workflow stops.

Technical Implementation

Phase 1: Preflight Checks

Before ANY changes, verify the environment:

# Working tree must be clean
git status --porcelain | head -20

# On correct branch
git branch --show-current  # Must be 'main'

# Last tag exists
git describe --tags --abbrev=0  # v4.4.0

# Version file exists
cat package.json | grep '"version"'  # 4.4.0
Enter fullscreen mode Exit fullscreen mode

Safety gate: If any check fails → STOP. No partial updates.

Phase 2: Commit Analysis

Parse git history to categorize changes:

# Get commits since last release
git log v4.4.0..HEAD --pretty=format:"%s"

# Categorize by type
git log v4.4.0..HEAD --format="%s" | \
  grep -iE "^(feat|fix|perf|security|BREAKING)"
Enter fullscreen mode Exit fullscreen mode

The output:

  • 20 features (→ MINOR bump)
  • 11 fixes
  • 0 breaking changes (would force MAJOR)

Phase 3: Intelligent Version Bump

Decision logic:

BREAKING changes → MAJOR (4.4.0 → 5.0.0)
Features only → MINOR (4.4.0 → 4.5.0)
Fixes only → PATCH (4.4.0 → 4.4.1)
No changes → SKIP (don't release)
Enter fullscreen mode Exit fullscreen mode

My release:

  • 20 features + 11 fixes → MINOR bump to 4.5.0

Phase 4: Atomic File Updates

Update ALL version references in one transaction:

# 1. package.json version
sed -i 's/"version": "4.4.0"/"version": "4.5.0"/' package.json

# 2. README badges
sed -i 's/version-4\.4\.0/version-4.5.0/g' README.md

# 3. Prepend CHANGELOG entry
# (Edit tool with full commit analysis)

# 4. Sync marketplace catalog
pnpm run sync-marketplace
Enter fullscreen mode Exit fullscreen mode

Key insight: All updates happen BEFORE any commit. Either everything succeeds or nothing changes.

Phase 5: Generate Changelog from Commits

Instead of manual summaries, parse git history:

## [4.5.0] - 2025-01-03

### 50-Vendor SaaS Skill Packs (500 Skills)
- Skill Databases: 105 vendor databases
- Flagship Packs: Supabase, Vercel, OpenRouter, Kling AI
- Template System: 30 Jinja2 slot templates

### ZCF Integration (Issue #184)
- MCP Registry manifests for 7 servers
- ZCF preset configuration
- BMAD workflows
- Tool routing documentation

### Statistics
| Metric | v4.4.0 | v4.5.0 | Change |
|--------|--------|--------|--------|
| Skills | 244 | 739 | +495 |
| Plugins | 258 | 260 | +2 |
Enter fullscreen mode Exit fullscreen mode

Auto-generated from git commits, not written by hand.

Phase 6: Release Execution

Commit, tag, and push in one atomic operation:

# Single commit with all changes
git add -A
git commit -m "chore(release): v4.5.0 - SaaS Skill Packs + ZCF Integration"

# Annotated tag with metadata
git tag -a v4.5.0 -m "Release v4.5.0: 50-Vendor SaaS Skill Packs..."

# Push both atomically
git push origin main && git push origin v4.5.0
Enter fullscreen mode Exit fullscreen mode

Rollback safety:

# If push fails, everything rolls back:
git tag -d v4.5.0
git reset --hard HEAD~1
Enter fullscreen mode Exit fullscreen mode

Phase 7: GitHub Release Automation

Create GitHub release with rich metadata:

gh release create v4.5.0 \
  --title "v4.5.0 - 50-Vendor SaaS Skill Packs + ZCF Integration" \
  --notes "## Release Highlights
- 50-Vendor SaaS Skill Packs (500 skills)
- ZCF Integration (5 phases)
- External Plugin Sync
..."
Enter fullscreen mode Exit fullscreen mode

Result: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/releases/tag/v4.5.0

What I Learned

1. Atomic Operations Are Critical

Before: Update files one-by-one → partial failures left repo in broken state

After: All updates happen before commit → either everything succeeds or nothing changes

2. Git History Is Your Source of Truth

Before: Manually write changelog from memory → miss commits, misrepresent changes

After: Parse git log for features/fixes → accurate, complete, automated

3. Safety Gates Prevent Disasters

Before: No validation → pushed broken releases multiple times

After: Each phase validates before proceeding:

  • Working tree clean?
  • Tests pass?
  • Version conflicts resolved?
  • Changelog generated?

4. Rollback Plans Are Mandatory

Before: If something failed mid-release → manual recovery, downtime

After: Each phase has explicit rollback:

# Tag failed to push?
git tag -d v4.5.0
git reset --hard HEAD~1

# GitHub release failed?
gh release delete v4.5.0 --yes
git push origin --delete v4.5.0
Enter fullscreen mode Exit fullscreen mode

5. Semver Automation Scales

The pattern:

  • Parse commits for feat:, fix:, BREAKING:
  • Calculate bump level automatically
  • No human decision needed

Works for:

  • 10 commits or 1,000 commits
  • Solo developer or 50-person team
  • Any language, any project

Results

Release v4.5.0 Shipped Successfully

Metric Value
Time to Ship 18 minutes (from /release to live)
Files Updated 3 (package.json, README, changelog)
Manual Steps 1 (approve the release)
Errors 0
Rollbacks Needed 0

What Got Shipped

  • Skills: 244 → 739 (+495 skills)
  • Plugins: 258 → 260
  • MCP Servers: 5 → 7
  • Skill Databases: 0 → 105

Automated Quality Gates

  • Working tree clean
  • All tests pass
  • Version files synced
  • Changelog generated
  • Tag created
  • GitHub release published

The Real Value

This isn't just about shipping v4.5.0 faster. It's about:

  1. Consistency - Every release follows the same workflow
  2. Auditability - Complete trail from commits → changelog → tag → release
  3. Safety - Gates prevent broken releases
  4. Scalability - Works for 10 commits or 1,000
  5. Knowledge Transfer - Anyone can run /release, no tribal knowledge

Try It Yourself

The /release skill is part of the Claude Code Plugins marketplace:

/plugin marketplace add jeremylongshore/claude-code-plugins
/plugin install release@claude-code-plugins-plus
Enter fullscreen mode Exit fullscreen mode

Run a release:

/release
Enter fullscreen mode Exit fullscreen mode

It will:

  1. Analyze your commits
  2. Suggest a version bump
  3. Generate a changelog
  4. Show you the plan
  5. Wait for your approval
  6. Execute atomically
  7. Roll back on any failure

Related Posts

What's Next

I'm working on:

  • Config-driven releases - .release.yml for team customization
  • Multi-repo releases - Coordinated releases across 3+ repos
  • Deployment automation - Auto-deploy after GitHub release
  • Smoke tests - Verify live deployment before announcing

Production release engineering isn't glamorous, but it's the difference between shipping with confidence and hoping nothing breaks.

Want to see the actual release? https://github.com/jeremylongshore/claude-code-plugins-plus-skills/releases/tag/v4.5.0

Top comments (0)