Skip to content

release-guide.md

Latest commit

 

History

History
229 lines (163 loc) · 4.79 KB

release-guide.md

File metadata and controls

229 lines (163 loc) · 4.79 KB

Release Guide

This document describes how to use the new changeset-based release process for the RTS project.

Overview

The release process now uses @changesets/cli for managing versions, changelogs, and publishing. This provides a more robust and standardized approach to releases.

Prerequisites

  1. Install changeset CLI:

    pnpm add -D @changesets/cli

  2. Initialize changeset (first time only):

    pnpm run changeset:init

Release Workflow

1. Create Changesets

When you make changes that should be released, create a changeset:

pnpm changeset

This will:

  • Ask you which packages have changed
  • Ask you what type of changes (patch, minor, major)
  • Ask you to write a description of the changes
  • Create a markdown file in .changeset/ directory

2. Build the Project

Before releasing, ensure the project builds correctly:

# Run tests
pnpm test

# Build the project (you need to implement this)
pnpm run build

# Validate build output
pnpm run release:build

3. Release

When ready to release:

# Full release process
pnpm run release

# Dry run (no actual changes)
pnpm run release:dry-run

The release process will:

  1. ✅ Check prerequisites (changeset installed, changeset files exist)
  2. ✅ Run tests (unless --skip-tests is used)
  3. ✅ Build project (unless --skip-build is used)
  4. ✅ Validate build output
  5. ✅ Update versions using changeset
  6. ✅ Publish to npm
  7. ✅ Push changes to git
  8. ✅ Create git tag for the release
  9. ✅ Clean up changeset files

Build Process

The release script expects a build process that produces the following files:

dist/
├── index.js
├── index.d.ts
├── resolver/
│   ├── index.js
│   └── index.d.ts
├── transformer/
│   ├── ts.js
│   └── ts.d.ts
└── config/
    ├── index.js
    └── index.d.ts

You need to implement the build script in package.json:

{
  "scripts": {
    "build": "your-build-command-here"
  }
}

Available Commands

Changeset Commands

  • pnpm changeset - Create a new changeset
  • pnpm run changeset:init - Initialize changeset (first time setup)
  • pnpm run changeset:version - Update versions and changelog
  • pnpm run changeset:publish - Publish to npm

Release Commands

  • pnpm run release - Full release process
  • pnpm run release:dry-run - Dry run (no actual changes)
  • pnpm run release:build - Build and validate
  • pnpm run release:test - Run tests only
  • pnpm run release:tag - Create git tag for current version

Options

  • --dry-run - Run without making actual changes
  • --skip-build - Skip the build process
  • --skip-tests - Skip running tests

Examples

Basic Release

# 1. Create changeset
pnpm changeset

# 2. Build and test
pnpm run build
pnpm test

# 3. Release
pnpm run release

Dry Run

# Test the release process without making changes
pnpm run release:dry-run

Skip Build

# Release without building (if build is already done)
pnpm run release --skip-build

Skip Tests

# Release without running tests
pnpm run release --skip-tests

Create Git Tag Only

# Create git tag for current version without full release
pnpm run release:tag

Changeset Files

Changeset files are created in .changeset/ directory with names like random-name.md. They contain:

---
"rts": patch
---

Description of changes

Changelog

The changelog is automatically generated by changeset and includes:

  • Version information
  • Release date
  • Categorized changes (Added, Changed, Fixed, Breaking Changes)
  • Links to relevant issues/PRs

Troubleshooting

Changeset Not Installed

pnpm add -D @changesets/cli

No Changeset Files

pnpm changeset

Build Validation Fails

Implement the build script in package.json and ensure it produces the expected files in dist/ directory.

Git Issues

Ensure you have proper git configuration and permissions to push to the repository.

Migration from Old Release Process

The old release process used manual version bumping. The new process:

  1. ✅ Uses changeset for version management
  2. ✅ Automatically generates changelog
  3. ✅ Provides better validation
  4. ✅ Supports multiple packages (future)
  5. ✅ Has better error handling

Best Practices

  1. Create changesets early - Create changesets as you make changes, not just before release
  2. Write clear descriptions - Good changelog entries help users understand changes
  3. Test before release - Always run tests and build validation
  4. Use dry runs - Test the release process with --dry-run first
  5. Review changes - Check the generated changelog before publishing