Skip to content

Latest commit

 

History

History
218 lines (150 loc) · 5.37 KB

RELEASES.md

File metadata and controls

218 lines (150 loc) · 5.37 KB

Release Guide

This guide explains how to create a new release of Whitespace.

GitHub Releases Overview

GitHub releases work by:

  1. Creating a git tag (e.g., v1.0.0)
  2. Pushing the tag to GitHub
  3. GitHub Actions automatically builds binaries for all platforms
  4. A release is created with the binaries attached

Prerequisites

  1. Ensure you have an NPM account and are logged in:

    pnpm login

  2. Add the NPM_TOKEN secret to your GitHub repository:

Creating a Release

Option 1: Automated Release (Recommended)

  1. Update version numbers in:

    • whitespace-cli/Cargo.toml
    • whitespace-core/Cargo.toml
    • whitespace-mcp/package.json

  2. Commit the version changes:

    git add -A
git commit -m "Bump version to v1.0.0"
git push

  3. Create and push a tag:

    git tag v1.0.0
git push origin v1.0.0

  4. GitHub Actions will automatically:

    • Build binaries for macOS (Intel & Apple Silicon) and Linux (x86_64 & ARM64)
    • Create a GitHub release with the binaries
    • Publish the MCP server to npm

Option 2: Manual Workflow Dispatch

You can also trigger a release manually from the GitHub Actions tab:

  1. Go to Actions → Release workflow
  2. Click "Run workflow"
  3. Enter the tag name (e.g., v1.0.0)
  4. Click "Run workflow"

Option 3: Local Build (for testing)

For testing release builds locally:

# Build for your current platform
./scripts/build-release.sh v1.0.0

# Output will be in release/v1.0.0/

Version Numbering

We follow Semantic Versioning (SemVer):

  • Major (1.0.0): Breaking changes
  • Minor (0.1.0): New features, backward compatible
  • Patch (0.0.1): Bug fixes, backward compatible

Pre-release versions:

  • Alpha: v1.0.0-alpha.1
  • Beta: v1.0.0-beta.1
  • Release Candidate: v1.0.0-rc.1

Component Versioning Policy

Whitespace consists of three independently versioned components:

1. CLI (whitespace-cli)

  • The core component that provides all functionality
  • Version defined in whitespace-cli/Cargo.toml
  • Released with tags: cli-v1.0.0

2. MCP Server (whitespace-mcp)

  • Node.js wrapper for AI integrations
  • Version defined in whitespace-mcp/package.json
  • Released with tags: mcp-v1.0.0
  • Must maintain compatibility with CLI version:
    • Major version must match CLI exactly
    • Minor version must be ≤ CLI minor version
    • Patch version is independent

3. VS Code Extension (whitespace-vscode)

  • IDE integration for VS Code and Cursor
  • Version defined in whitespace-vscode/package.json
  • Released with tags: vscode-v1.0.0
  • Must maintain compatibility with CLI version:
    • Major version must match CLI exactly
    • Minor version must be ≤ CLI minor version
    • Patch version is independent

Version Compatibility Examples

CLI Version MCP/VS Code Version Compatible? Reason
2.3.1 2.0.5 ✅ Major matches, minor 0 ≤ 3
2.3.1 2.3.9 ✅ Major matches, minor 3 ≤ 3
2.3.1 2.4.0 ❌ Minor 4 > 3 (might use unavailable features)
2.3.1 3.0.0 ❌ Major version mismatch
1.0.0 1.0.0 ✅ Exact match

Releasing Individual Components

Each component has its own release workflow:

# Release CLI
git tag cli-v1.0.0
git push origin cli-v1.0.0

# Release MCP Server
git tag mcp-v1.0.0
git push origin mcp-v1.0.0

# Release VS Code Extension
git tag vscode-v1.0.0
git push origin vscode-v1.0.0

Version Verification

Both MCP and VS Code extensions verify CLI compatibility on startup:

# CLI provides version info
whitespace version --output json
# {"name":"whitespace","version":"1.0.0"}

If the CLI version doesn't meet requirements, the MCP server and VS Code extension will fail with a clear error message indicating the version mismatch.

Platform Support

The release workflow builds for:

  • macOS Intel (x86_64-apple-darwin)
  • macOS Apple Silicon (aarch64-apple-darwin)
  • Linux x86_64 (x86_64-unknown-linux-gnu)
  • Linux ARM64 (aarch64-unknown-linux-gnu)

Release Artifacts

Each release includes:

  • whitespace-macos-amd64.tar.gz - macOS Intel binary
  • whitespace-macos-arm64.tar.gz - macOS Apple Silicon binary
  • whitespace-linux-amd64.tar.gz - Linux x86_64 binary
  • whitespace-linux-arm64.tar.gz - Linux ARM64 binary
  • Source code (automatically included by GitHub)

NPM Package

The MCP server is published to npm as @whitespace/mcp-server.

Users can install it with:

npx @whitespace/mcp-server

Troubleshooting

Build Failures

If the release build fails:

  1. Check the GitHub Actions logs for errors
  2. Ensure all tests pass locally
  3. Verify Cargo.toml versions match

NPM Publishing Issues

If npm publishing fails:

  1. Verify the NPM_TOKEN secret is set correctly
  2. Check that the package name is available
  3. Ensure package.json is valid

Cross-Compilation Issues

For Linux ARM64 builds from x86_64:

  • The workflow uses cross for cross-compilation
  • This requires Docker to be available in the CI environment

Post-Release

After a successful release:

  1. Update the documentation if needed
  2. Announce the release (optional)
  3. Start working on the next version!