gh-slamb2k-mad-skills-dev-flow/skills/start-right/references/release-strategies.md

Release Strategies Reference

This document provides detailed guidance on different release strategies and deployment targets.

npm Package Release

Best for: JavaScript/TypeScript libraries, CLI tools, frameworks

Prerequisites:

• npm account and NPM_TOKEN secret configured
• package.json with correct metadata (name, version, main, types)
• Build output in publishable state

Workflow steps:

1. Build the package
2. Run npm publish
3. Create GitHub Release with version tag
4. Include link to npm package in release notes

Configuration:

{
  "name": "@username/package-name",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

GitHub Release notes example:

📦 Published to npm: https://www.npmjs.com/package/@username/package-name

Install with:
npm install @username/package-name

GitHub Pages Deployment

Best for: Static websites, documentation sites, SPAs

Prerequisites:

• GitHub Pages enabled in repository settings
• Build outputs static files to a directory (usually dist/ or build/)

Workflow steps:

1. Build the static site
2. Deploy to gh-pages branch using peaceiris/actions-gh-pages
3. Create GitHub Release with link to live site

Configuration considerations:

• Set correct base path for SPAs (e.g., Vite: base: '/repo-name/')
• Configure 404.html for SPA routing
• Custom domain setup (optional)

GitHub Release notes example:

🌐 Deployed to: https://username.github.io/repo-name

Changes in this release:
[auto-generated release notes]

Vercel Deployment

Best for: Next.js apps, React apps, modern web frameworks

Prerequisites:

• Vercel account connected to GitHub
• Vercel project configured (can be done via CLI or UI)

Workflow approaches:

Option 1: Automatic (Recommended)

• Let Vercel handle deployment via their GitHub integration
• GitHub Actions only handles validation
• Every push to main triggers Vercel deployment automatically

Option 2: Manual via GitHub Actions

• Use Vercel CLI in GitHub Actions
• Requires VERCEL_TOKEN secret
• More control but more complex

GitHub Release notes example:

🚀 Deployed to Vercel: https://project-name.vercel.app

Production URL: https://your-domain.com (if custom domain)

Docker Container Release

Best for: Microservices, backend applications, full-stack apps

Prerequisites:

• Dockerfile in repository
• Multi-stage builds for optimization (recommended)

Release targets:

• GitHub Container Registry (ghcr.io) - Recommended, free with GitHub
• Docker Hub - Public registry, widely used
• AWS ECR, Google GCR, Azure ACR - Cloud-specific registries

Workflow steps:

1. Build Docker image with version tag
2. Push to container registry
3. Also tag as latest
4. Create GitHub Release with pull command

Best practices:

• Use multi-stage builds to minimize image size
• Run containers as non-root user
• Include health check in Dockerfile
• Version images with semantic versioning

GitHub Release notes example:

🐳 Docker image: `ghcr.io/username/repo-name:v1.2.3`

Pull and run:
docker pull ghcr.io/username/repo-name:v1.2.3
docker run -p 8080:8080 ghcr.io/username/repo-name:v1.2.3

Binary Artifacts Release

Best for: CLI tools, desktop apps, native applications

Platforms to support:

• Linux (x86_64, arm64)
• macOS (x86_64, arm64/Apple Silicon)
• Windows (x86_64)

Workflow approaches:

Option 1: GitHub Actions matrix build

Build on multiple runners (ubuntu, macos, windows) and upload artifacts

Option 2: Cross-compilation

Compile for multiple targets from single runner (works for Go, Rust)

Option 3: GoReleaser / cargo-dist

Use specialized tools for automated multi-platform releases

GitHub Release notes example:

📥 Download the binary for your platform:

- Linux x86_64: [app-linux-amd64](link)
- Linux ARM64: [app-linux-arm64](link)
- macOS x86_64: [app-darwin-amd64](link)
- macOS ARM64: [app-darwin-arm64](link)
- Windows x86_64: [app-windows-amd64.exe](link)

Quick install:
curl -L https://github.com/user/repo/releases/download/v1.2.3/app-linux-amd64 -o app
chmod +x app
./app

Python Package (PyPI) Release

Best for: Python libraries, CLI tools, frameworks

Prerequisites:

• PyPI account and API token
• pyproject.toml or setup.py with metadata
• Build tool (build, setuptools, poetry)

Workflow steps:

1. Build distribution packages (wheel + sdist)
2. Upload to PyPI using twine
3. Create GitHub Release with PyPI link

Configuration:

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
description = "Package description"
authors = [{name = "Your Name", email = "you@example.com"}]

GitHub Release notes example:

📦 Published to PyPI: https://pypi.org/project/my-package/

Install with:
pip install my-package

Rust Crate (crates.io) Release

Best for: Rust libraries

Prerequisites:

• crates.io account
• CARGO_REGISTRY_TOKEN secret
• Cargo.toml with complete metadata

Workflow steps:

1. Run tests and validation
2. Publish to crates.io using cargo publish
3. Create GitHub Release

GitHub Release notes example:

📦 Published to crates.io: https://crates.io/crates/my-crate

Add to your Cargo.toml:
[dependencies]
my-crate = "1.0.0"

Claude Code Skill Release

Best for: Claude Code skills and extensions

Prerequisites:

• Skill properly structured and validated
• Skill packaged as .skill file

Workflow steps:

1. Validate skill structure
2. Package skill into .skill file
3. Create GitHub Release with .skill file attached
4. No deployment needed

GitHub Release notes example:

🎯 Claude Code Skill Release

Download the skill file and install in Claude Code:
1. Download [skill-name.skill](link)
2. In Claude Code, run: /skills install /path/to/skill-name.skill

What's included:
- [Brief description of skill capabilities]

Desktop App Distribution

Best for: Electron apps, Tauri apps

Platforms: Windows, macOS, Linux

Workflow tools:

• Electron Builder: Automated builds and updates
• Tauri: Rust-based alternative with smaller bundle sizes

Distribution methods:

• GitHub Releases with auto-updater
• Platform-specific stores (Microsoft Store, Mac App Store)
• Custom update server

Platform-as-a-Service (PaaS) Deployment

Platforms: Railway, Fly.io, Render, Heroku (legacy)

Common characteristics:

• Git-based deployment
• Automatic container building
• Built-in databases and add-ons
• Easy environment variable management

Workflow integration: Most PaaS platforms integrate directly with GitHub - just validation in GitHub Actions, deployment handled by platform

Release Strategy Selection Guide

Choose npm/PyPI/crates.io when:

• Building a library or package
• Want maximum distribution reach
• Package manager installation is preferred

Choose GitHub Pages when:

• Pure static site
• Documentation site
• No server-side logic needed
• Want simple, free hosting

Choose Vercel/Netlify when:

• Modern framework (Next.js, SvelteKit, etc.)
• Need serverless functions
• Want preview deployments for PRs
• Need automatic optimizations

Choose Docker when:

• Microservices architecture
• Need consistent runtime environment
• Deploying to Kubernetes or container orchestration
• Complex dependencies

Choose Binary release when:

• CLI tool
• Desktop application
• Want users to run without installing runtime
• Performance-critical application

Choose PaaS when:

• Full-stack web application
• Need managed database
• Want simple deployment
• Solo developer or small team

Multi-Release Strategy

Some projects benefit from multiple release targets:

Example: CLI tool

• npm package (for Node.js users)
• Standalone binary (for system installation)
• Docker image (for containerized environments)

Example: Web framework

• npm package (for developers)
• Documentation site on GitHub Pages
• Example deployed to Vercel

Example: Library

• Language package registry (npm, PyPI, etc.)
• GitHub Releases for changelogs
• Documentation site

Versioning and Changelog Best Practices

Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Auto-versioning: Use commit messages or PR labels to determine version bump:

• feat: → MINOR bump
• fix: → PATCH bump
• BREAKING CHANGE: → MAJOR bump

Changelog generation:

• Auto-generate from commit messages (Conventional Commits)
• Auto-generate from PR titles
• Use GitHub's release notes generation
• Tools: semantic-release, conventional-changelog