Skip to content

RELEASE.md

Latest commit

 

History

History
172 lines (126 loc) · 6.34 KB

RELEASE.md

File metadata and controls

172 lines (126 loc) · 6.34 KB

Release Process

This document explains how releases work for the MCP REST API project.

Overview

We use Release Please by Google to manage releases. This gives us:

  • Controlled releases: You decide when to release by merging a PR
  • Automatic changelogs: Generated from conventional commit messages
  • Semantic versioning: Version bumps based on commit types
  • No accidental releases: Commits to main don't automatically publish

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Release Flow                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. Merge feature/fix PRs to main (normal development)         │
│                         │                                       │
│                         ▼                                       │
│   2. Release Please automatically creates/updates a             │
│      "Release PR" with changelog and version bump               │
│                         │                                       │
│                         ▼                                       │
│   3. The Release PR stays open, accumulating changes            │
│      (you can merge more features, it updates automatically)    │
│                         │                                       │
│                         ▼                                       │
│   4. When YOU'RE READY: merge the Release PR                    │
│                         │                                       │
│                         ▼                                       │
│   5. GitHub Release is created automatically                    │
│                         │                                       │
│                         ▼                                       │
│   6. NPM package is published automatically                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

For Contributors

Writing Commits

We use Conventional Commits. Your commit messages determine version bumps:

Commit Type Version Bump Example
feat: Minor (0.4.0 → 0.5.0) feat: add file upload support
fix: Patch (0.4.0 → 0.4.1) fix: handle empty response body
perf: Patch perf: optimize large response handling
refactor: Patch refactor: simplify auth logic
BREAKING CHANGE: Major (0.4.0 → 1.0.0) Footer in commit body

These commit types are tracked but don't trigger version bumps:

  • docs: - Documentation changes
  • test: - Adding or updating tests
  • ci: - CI/CD configuration
  • build: - Build system changes
  • chore: - Maintenance tasks
  • style: - Code formatting

Example Workflow

# 1. Create a feature branch
git checkout -b feat/new-feature

# 2. Make changes and commit with conventional format
git commit -m "feat: add support for custom timeout"

# 3. Push and create PR
git push -u origin feat/new-feature
gh pr create

# 4. After PR is merged to main, Release Please updates the Release PR
# 5. Maintainer merges Release PR when ready to publish

For Maintainers

Releasing a New Version

  1. Check the Release PR: Look for a PR titled "chore(main): release X.Y.Z"
  2. Review the changelog: Ensure it accurately reflects the changes
  3. Merge when ready: Merging triggers the release

That's it! The automation handles:

  • Creating the GitHub release
  • Publishing to NPM
  • Updating the changelog

What If There's No Release PR?

If no Release PR exists, it means there are no releasable changes since the last release. Only feat:, fix:, perf:, and refactor: commits trigger release PRs.

Manual Release (Emergency)

If you need to release manually (not recommended):

# Update version
npm version patch  # or minor/major

# Push with tags
git push --follow-tags

# Create GitHub release manually
gh release create v0.4.1 --generate-notes

# NPM publish will trigger automatically on release

Configuration Files

File Purpose
release-please-config.json Release Please settings (includes changelog sections)
.release-please-manifest.json Current version tracker
.github/workflows/release-please.yml Creates/updates Release PR
.github/workflows/npm-publish.yml Publishes to NPM on release
commitlint.config.js Commit message validation

Version Numbering

We follow Semantic Versioning:

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes, performance improvements
  │     └──────── New features (backwards compatible)
  └────────────── Breaking changes

While in 0.x.x (pre-1.0), minor versions may include breaking changes.

FAQ

Why not release on every commit?

Batching changes into deliberate releases:

  • Gives users predictable update cycles
  • Allows grouping related features
  • Provides meaningful changelogs
  • Reduces notification fatigue

Can I release multiple times a day?

Yes! Merge the Release PR whenever you want. A new Release PR will be created after the next releasable commit.

What if I need to fix a release?

  1. Create a fix PR with fix: commit
  2. Merge to main
  3. Release Please updates the Release PR
  4. Merge the Release PR to publish the fix

How do I do a breaking change?

Add BREAKING CHANGE: in the commit footer:

feat: change API response format

BREAKING CHANGE: Response structure changed from array to object.
Users must update their code to handle the new format.

This will trigger a major version bump (0.x → 1.0 or 1.x → 2.0).