Publishing New Versions

Release process and version management for MSR.

Table of contents

  1. Overview
  2. Semantic Versioning
    1. Pre-1.0 Development
  3. Release Checklist
    1. 1. Pre-Release Verification
    2. 2. Version Bump
    3. 3. Update Documentation
    4. 4. Build and Test
    5. 5. Publish to npm
    6. 6. Post-Publication
  4. Version Numbering Guidelines
    1. Patch Release (0.3.0 → 0.3.1)
    2. Minor Release (0.3.0 → 0.4.0)
    3. Major Release (0.x.0 → 1.0.0)
  5. Breaking Changes Policy
    1. What Constitutes a Breaking Change
    2. How to Handle Breaking Changes
    3. Breaking Changes
  6. Release Automation
    1. CI/CD Pipeline
    2. NPM Scripts for Release
  7. Hotfix Process
    1. 1. Create Hotfix Branch
    2. 2. Fix the Bug
    3. 3. Fast-Track Release
  8. Version History
    1. Maintaining CHANGELOG.md
  9. npm Package Configuration
    1. package.json Essentials
  10. Rollback a Release
    1. 1. Deprecate on npm
    2. 2. Publish Fixed Version
    3. 3. Update Documentation
  11. Quick Reference

Overview

This document describes the process for releasing new versions of Migration Script Runner and publishing them to npm.

Semantic Versioning

MSR follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH
  • MAJOR (x.0.0) - Incompatible API changes
  • MINOR (0.x.0) - New features, backward compatible
  • PATCH (0.0.x) - Bug fixes, backward compatible

Pre-1.0 Development

During v0.x development:

  • Minor versions MAY include breaking changes
  • Always provide migration guides for breaking changes
  • Major version 1.0.0 will be first stable release

Release Checklist

1. Pre-Release Verification

  • All tests pass (npm test)
  • 100% test coverage maintained
  • No linting errors (npm run lint)
  • Mutation testing passes (npm run test:mutation)
  • All CI/CD checks pass
  • Documentation is up-to-date
  • CHANGELOG.md is updated
  • Migration guide created (if breaking changes)

2. Version Bump 

# Update version in package.json
npm version patch   # Bug fixes (0.3.0 → 0.3.1)
npm version minor   # New features (0.3.0 → 0.4.0)
npm version major   # Breaking changes (0.3.0 → 1.0.0)

This command:

  • Updates package.json version
  • Creates a git commit
  • Creates a git tag

3. Update Documentation

Update these files:

  1. CHANGELOG.md 
    ## [0.4.0] - 2025-01-28

### Added
- New feature X
- New feature Y

### Changed
- Updated behavior of Z

### Fixed
- Bug fix A
- Bug fix B

### Breaking Changes
- API change C
  2. README.md (if needed)
    • Update version badges
    • Update examples if API changed
  3. Migration Guide (if breaking changes)
    • Create do../version-migration/v0.X-to-v0.Y.md
    • BEFORE/AFTER code examples
    • Step-by-step migration instructions

4. Build and Test 

# Clean build
rm -rf dist node_modules
npm install
npm run build

# Run full test suite
npm test

# Verify coverage
npm run test:coverage

# Run mutation tests
npm run test:mutation

5. Publish to npm 

# Login to npm (if not already)
npm login

# Publish (dry run first)
npm publish --dry-run

# Publish for real
npm publish --access public

6. Post-Publication

  1. Push to GitHub 
    git push origin master --tags
  2. Create GitHub Release
    • Go to GitHub → Releases → “Draft a new release”
    • Select the version tag
    • Title: v0.4.0
    • Description: Copy from CHANGELOG.md
    • Attach any binaries if needed
  3. Announce Release
    • Update project README
    • Post in discussions if major release
    • Tweet/social media if significant

Version Numbering Guidelines

Patch Release (0.3.0 → 0.3.1)

When:

  • Bug fixes only
  • No new features
  • No breaking changes
  • Documentation fixes

Example:

v0.3.1
- Fixed array mutation bug in RollbackService
- Fixed typo in documentation

Minor Release (0.3.0 → 0.4.0)

When:

  • New features
  • Backward compatible
  • May include bug fixes
  • May include deprecations

Example:

v0.4.0
- Added MySQL handler support
- Added new configuration option: retryAttempts
- Fixed backup path resolution

Major Release (0.x.0 → 1.0.0)

When:

  • Breaking API changes
  • Significant architectural changes
  • Removed deprecated features

Example:

v1.0.0
- BREAKING: migrate() now returns Promise<Result>
- BREAKING: Removed deprecated cfg property from handler
- Added comprehensive migration guide

Breaking Changes Policy

What Constitutes a Breaking Change

  • API Changes: Method signature changes, parameter removal
  • Behavior Changes: Different default behavior
  • Removals: Removing public APIs or features
  • Type Changes: TypeScript interface changes

How to Handle Breaking Changes

  1. Document in CHANGELOG ```markdown

    Breaking Changes

    • migrate() return type: Changed from void to IMigrationResult
    • Migration Required: See migration guide for upgrade path ```
  2. Create Migration Guide
    • File: do../version-migration/v0.X-to-v0.Y.md
    • Include BEFORE/AFTER examples
    • Step-by-step instructions
    • Explain rationale for change
  3. Update API Documentation
    • Mark old behavior as deprecated (if transitioning)
    • Document new behavior
    • Add breaking change notice
  4. Consider Deprecation Period
    • For major changes, deprecate first in minor version
    • Remove in next major version
    • Give users time to migrate

Release Automation

CI/CD Pipeline

On Push to Master:

  1. Run tests
  2. Check coverage (must be 100%)
  3. Run linting
  4. Build package
  5. Run mutation tests (optional)

On Tag Push:

  1. All of the above
  2. Publish to npm (if tests pass)
  3. Create GitHub release

NPM Scripts for Release 

# Pre-release checks
npm run prerelease

# This could run:
# - npm test
# - npm run test:coverage
# - npm run lint
# - npm run build

Hotfix Process

For critical bugs in production:

1. Create Hotfix Branch 

git checkout -b hotfix/critical-bug master

2. Fix the Bug

  • Minimal changes only
  • Focus on the specific issue
  • Add regression test

3. Fast-Track Release 

# Test
npm test

# Version bump (patch)
npm version patch

# Publish
npm publish

# Merge back to master
git checkout master
git merge hotfix/critical-bug
git push origin master --tags

Version History

Maintaining CHANGELOG.md

Format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Added
- Features in development

## [0.3.0] - 2025-01-28
### Added
- Checksum integrity checking
- Path traversal security validation

### Changed
- Config now separate parameter (breaking)

### Fixed
- Array mutation in RollbackService

## [0.2.0] - 2024-12-15
...

npm Package Configuration

package.json Essentials 

{
  "name": "@migration-script-runner/core",
  "version": "0.3.0",
  "description": "Migration Script Runner - Core Framework",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "/dist"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/migration-script-runner/msr-core.git"
  },
  "keywords": [
    "migration",
    "database",
    "typescript"
  ],
  "license": "MIT"
}

Important Fields:

  • files: Only include dist/ in npm package
  • main: Entry point for require()
  • types: TypeScript definitions
  • repository: Link to GitHub

Rollback a Release

If a release has critical issues:

1. Deprecate on npm 

npm deprecate @migration-script-runner/core@0.4.0 "Critical bug, use 0.4.1"

2. Publish Fixed Version 

npm version patch
npm publish

3. Update Documentation

  • Mark version as deprecated in CHANGELOG
  • Link to fixed version
  • Explain the issue

Quick Reference

Task Command
Bump patch version npm version patch
Bump minor version npm version minor
Bump major version npm version major
Publish (dry run) npm publish --dry-run
Publish to npm npm publish --access public
Deprecate version npm deprecate <pkg>@<version> "<message>"
View published versions npm view @migration-script-runner/core versions