Skip to content

RELEASE.md

Latest commit

 

History

History
162 lines (107 loc) · 4.79 KB

RELEASE.md

File metadata and controls

162 lines (107 loc) · 4.79 KB

Release and Publish Guide

This document describes how to create releases and publish the @currents/mcp package to npm.

Overview

The release process is split into two steps:

  1. Create Release - Bumps version, updates changelog, creates git tag and GitHub release
  2. Publish to NPM - Builds and publishes the package to npm

This separation allows for testing releases before publishing and supports multiple npm distribution channels (alpha, beta, latest).

Prerequisites

  • Push access to the repository
  • For npm publishing: NPM_TOKEN secret configured in GitHub repository settings

Creating a Release

Releases are created via GitHub Actions or locally using release-it with conventional commits.

Steps

  1. Go to Actions → Create Release
  2. Click Run workflow
  3. Optionally enable Dry run to preview changes without creating an actual release
  4. Click Run workflow

What happens

The workflow will:

  1. Run the test suite
  2. Analyze commits since the last tag to determine the version bump:
    • feat: commits → minor version bump (e.g., 2.1.0 → 2.2.0)
    • fix: commits → patch version bump (e.g., 2.1.0 → 2.1.1)
    • BREAKING CHANGE: in commit body → major version bump (e.g., 2.1.0 → 3.0.0)
  3. Update CHANGELOG.md with new entries
  4. Bump version in package.json
  5. Create a git commit: chore: release v<version>
  6. Create a git tag: v<version>
  7. Create a GitHub release with auto-generated notes

Requirements

  • Must be run from the main branch
  • Working directory must be clean (no uncommitted changes)

Publishing to NPM

After creating a release, publish to npm via GitHub Actions.

Steps

  1. Go to Actions → Publish NPM Package
  2. Click Run workflow
  3. Select the NPM tag (distribution channel):
    • alpha - Early development versions
    • beta - Pre-release versions for testing
    • latest - Stable production releases
    • oldversion - For publishing older/patched versions
  4. Click Run workflow

What happens

The workflow will:

  1. Build the TypeScript project
  2. Copy README.md from the repository root to mcp-server/
  3. Clean devDependencies from package.json for a lighter package
  4. Run npm pack --dry-run to preview the package contents
  5. Publish to npm with the selected tag

Recommended Release Flow

For a typical release:

  1. Create Release → creates version 2.3.0
  2. Publish to NPM with tag beta → users can install with npm install @currents/mcp@beta
  3. Test the beta release
  4. Promote beta to latest (or publish again with latest tag)

Promoting Beta to Latest

To promote a beta release to the latest tag without re-publishing:

Steps

  1. Go to Actions → NPM - Promote beta to latest
  2. Click Run workflow
  3. Enter the version to promote (e.g., 2.3.0)
  4. Click Run workflow

What happens

The workflow will:

  1. Add the latest dist-tag to the specified version
  2. Remove the beta dist-tag from that version

This is useful when you've tested a beta release and want to make it the default install without rebuilding.

Local Development

Dry Run Release Locally

cd mcp-server
npm run release:dry

Manual Publishing (not recommended)

If you need to publish manually:

cd mcp-server
npm run publish:mcp -- -- --tag beta

Note: This requires NPM_TOKEN to be set in your environment and will modify local files.

Troubleshooting

Release fails with "working directory not clean"

Commit or stash your changes before running the release workflow.

Release fails with "not on main branch"

The release workflow must be triggered from the main branch. Merge your changes first.

npm publish fails with authentication error

Verify the NPM_TOKEN secret is correctly configured in the repository settings.

README not showing on npm

The publish script copies README.md from the repository root. Ensure the root README exists and is not empty.

Commit Message Guidelines

Follow Conventional Commits for automatic version bumping:

feat: add new tool for fetching test artifacts
fix: handle missing API key gracefully
docs: update setup instructions
chore: update dependencies
refactor: simplify request handling

feat!: redesign API response format
BREAKING CHANGE: response structure has changed
Prefix Version Bump Example
feat: Minor 2.1.0 → 2.2.0
fix: Patch 2.1.0 → 2.1.1
feat!: or BREAKING CHANGE: Major 2.1.0 → 3.0.0
docs:, chore:, refactor: No bump -