Version and Changelog Management

Changeset is a tool for managing versions and generating changelogs, especially suitable for Monorepo projects. This guide details how to use Changeset to manage versions and releases for VUP projects.

What is Changeset

Changeset is a version management tool that provides:

• Semantic Versioning - Automatic version number management
• Changelog Generation - Automatic generation of detailed changelogs
• Monorepo Support - Support for multi-package version management
• Release Management - Automated release process
• Change Tracking - Track the impact of each change

Quick Start

VUP project has Changeset pre-configured and ready to use:

1. View Existing Configuration

# View .changeset directory
ls .changeset/

# View configuration file
cat .changeset/config.json

2. Add Changes

# Add change records
pnpm changeset

# Select change type
# - patch: Bug fixes
# - minor: New features
# - major: Breaking changes

3. Generate Versions

# Generate version updates
pnpm changeset version

# Publish changes
pnpm changeset publish

Change Types

Patch (Patch Version)

Used for bug fixes and minor improvements:

# Example: Fix login issue
- Fix user login failure issue
- Optimize error message display

Version Change: 1.0.0 → 1.0.1

Minor (Minor Version)

Used for new features and backward-compatible improvements:

# Example: Add new features
- Add user avatar upload feature
- Add dark mode support
- Optimize page loading speed

Version Change: 1.0.0 → 1.1.0

Major (Major Version)

Used for breaking changes:

# Example: Breaking changes
- Refactor API interface, remove old version support
- Change component API structure
- Upgrade dependency versions, requires Node.js 18+

Version Change: 1.0.0 → 2.0.0

Project Configuration

.changeset/config.json

{
  "$schema": "https://unpkg.com/@changesets/config@2.3.1/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

package.json Scripts

{
  "scripts": {
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "changeset publish"
  }
}

Workflow

1. Develop New Features

# Create feature branch
git checkout -b feature/new-feature

# Develop feature
# ... write code ...

# Commit code
git add .
git commit -m "feat: add new feature"

2. Add Change Records

# Add change records
pnpm changeset

# Select change type
? Select a package: @vup/cli
? Select a package: @vup/templates
? Select a package: @vup/docs
? What kind of change is this for @vup/cli? minor
? What kind of change is this for @vup/templates? patch
? What kind of change is this for @vup/docs? patch
? Please enter a summary for this change: Add new feature support

3. Commit Changes

# Commit change records
git add .
git commit -m "chore: add changeset for new feature"
git push origin feature/new-feature

4. Merge to Main Branch

# Merge PR
git checkout main
git pull origin main

# Generate version updates
pnpm changeset version

# Commit version updates
git add .
git commit -m "chore: version packages"
git push origin main

5. Release Version

# Publish to NPM
pnpm changeset publish

# Create Git tag
git tag v1.1.0
git push origin v1.1.0

Changelog Format

Auto-generated Changelog

# @vup/cli

## 1.1.0

### Minor Changes

- Add new feature support

## 1.0.1

### Patch Changes

- Fix login issue
- Optimize error messages

Manually Added Changelog

# Changelog

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

## [1.1.0] - 2024-01-15

### Added

- Add user avatar upload feature
- Add dark mode support
- Optimize page loading speed

### Changed

- Update dependency versions
- Optimize build configuration

### Fixed

- Fix login failure issue
- Fix page refresh issue

## [1.0.0] - 2024-01-01

### Added

- Initial version release
- Basic feature implementation

Multi-package Management

Link Package Versions

Configure in .changeset/config.json:

{
  "linked": [
    ["@vup/cli", "@vup/templates"],
    ["@vup/docs", "@vup/homepage"]
  ]
}

Fixed Package Versions

{
  "fixed": [["@vup/cli", "@vup/templates", "@vup/docs"]]
}

Release Strategy

Automatic Release

Use GitHub Actions for automatic release:

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          registry-url: https://registry.npmjs.org/
      - run: pnpm install
      - run: pnpm changeset version
      - run: pnpm changeset publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Manual Release

# Check changes
pnpm changeset status

# Generate versions
pnpm changeset version

# Publish packages
pnpm changeset publish

Best Practices

1. Change Records

• Use clear and concise descriptions
• Include the scope of impact
• Follow semantic versioning standards

2. Version Management

• Release versions regularly
• Avoid accumulating changes for too long
• Maintain consistency in version numbers

3. Changelog

• Keep changelog complete
• Use unified format
• Update and maintain regularly

4. Release Process

• Test thoroughly before release
• Use automation tools to reduce errors
• Maintain consistency in release process

Common Issues

Issue 1: Missing Change Records

Cause: Forgot to commit .changeset directory

Solution:

# Check change records
ls .changeset/

# Add change records
git add .changeset/
git commit -m "chore: add changeset"

Issue 2: Version Conflicts

Cause: Multiple package versions don't match

Solution:

# Check version status
pnpm changeset status

# Manually adjust versions
pnpm changeset version

Issue 3: Release Failure

Cause: NPM authentication or network issues

Solution:

# Check NPM authentication
npm whoami

# Re-login
npm login

# Retry release
pnpm changeset publish

Related Resources

• Changeset Official Documentation
• Semantic Versioning Specification
• NPM Publishing Guide
• GitHub Actions Configuration