Version and Changelog Management

Release-it is a modern release management tool that automates the versioning and publishing process. This guide details how to use Release-it to manage versions and releases for VUP projects.

What is Release-it

Release-it is a release management tool that provides:

Semantic Versioning - Automatic version number management based on commit messages
Changelog Generation - Automatic generation of detailed changelogs from commits
Git Workflow - Automatic Git tag creation and version commits
NPM Integration - Optional NPM package publishing
Extensible - Plugin support for GitHub releases, Slack notifications, etc.

Quick Start

VUP project has Release-it pre-configured and ready to use:

1. View Existing Configuration

bash

# View configuration in package.json
cat package.json | grep -A 20 '"release-it"'

2. Create a Release

bash

# Create a new release
pnpm release

# Or with npm
npm run release

3. Release Process

Release-it will:

Bump the version in package.json
Update CHANGELOG.md
Create a Git tag
Commit the changes
Optionally publish to NPM

Version Types

Patch (Patch Version)

Bug fixes and minor improvements:

bash

# Commit message: fix: resolve login issue
# Version Change: 1.0.0 → 1.0.1

Example Commit:

bash

git commit -m "fix: resolve user login failure issue"

Minor (Minor Version)

New features and backward-compatible improvements:

bash

# Commit message: feat: add user avatar upload
# Version Change: 1.0.0 → 1.1.0

Example Commit:

bash

git commit -m "feat: add user avatar upload feature"

Major (Major Version)

Breaking changes:

bash

# Commit message: feat!: refactor API interface
# Version Change: 1.0.0 → 2.0.0

Example Commit:

bash

git commit -m "feat!: refactor API interface, remove old version support"

Project Configuration

package.json

json

{
  "scripts": {
    "release": "release-it"
  },
  "devDependencies": {
    "release-it": "^19.0.5",
    "@release-it/conventional-changelog": "^10.0.1"
  },
  "release-it": {
    "plugins": {
      "@release-it/conventional-changelog": {
        "preset": "angular",
        "infile": "CHANGELOG.md"
      }
    },
    "git": {
      "commitMessage": "chore: release v${version}",
      "requireCleanWorkingDir": false,
      "requireUpstream": false,
      "commit": true,
      "tag": true,
      "push": false
    },
    "npm": {
      "publish": false
    }
  }
}

Workflow

1. Develop New Features

bash

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

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

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

2. Commit Message Format

Follow Conventional Commits specification:

bash

# Format: <type>(<scope>): <subject>

# Types:
feat:     # New feature
fix:      # Bug fix
docs:     # Documentation changes
style:    # Code style changes (formatting)
refactor: # Code refactoring
test:     # Adding tests
chore:    # Maintenance tasks

# Examples:
git commit -m "feat: add dark mode support"
git commit -m "fix: resolve login issue"
git commit -m "docs: update README"

3. Create a Release

bash

# Run release command
pnpm release

# Release-it will prompt:
# ? Select increment (next version): patch/minor/major
# ? Git tag: v1.1.0
# ? Create a GitHub Release? Yes/No

4. Review and Push

bash

# Review changes
git log --oneline

# Push changes and tags
git push origin main
git push --tags

Changelog Format

Auto-generated Changelog

Release-it uses @release-it/conventional-changelog to automatically generate changelogs:

markdown

# Changelog

# [1.6.0](/compare/v1.5.0...v1.6.0) (2024-01-15)

### Features

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

### Bug Fixes

- Fix login failure issue
- Fix page refresh issue
- Fix error message display

### Documentation

- Update README
- Add deployment guide

# [1.5.0](/compare/v1.4.0...v1.5.0) (2024-01-01)

### Features

- Initial version release
- Basic feature implementation

Commit Message Types

Type	Description	Version Bump
`feat`	New feature	Minor
`fix`	Bug fix	Patch
`feat!` or `BREAKING CHANGE:`	Breaking change	Major
`docs`	Documentation	None
`style`	Code style	None
`refactor`	Refactoring	Patch (minor with `refactor!`)
`test`	Tests	None
`chore`	Maintenance	None
`perf`	Performance	Patch
`ci`	CI/CD	None

Release Strategy

Manual Release

bash

# Check current version
cat package.json | grep version

# Create release
pnpm release

# Review generated changelog
cat CHANGELOG.md

Interactive Release

bash

# Run with prompts
pnpm release

# Output:
# ℹ Current version: 1.5.0
# ? Select increment (next version):
#   1. Patch (1.5.0 → 1.5.1)
#   2. Minor (1.5.0 → 1.6.0)
#   3. Major (1.5.0 → 2.0.0)
#   4. Other...

Pre-release

bash

# Create pre-release (e.g., alpha, beta, rc)
pnpm release --preRelease=alpha
pnpm release --preRelease=beta
pnpm release --preRelease=rc

# Version: 1.6.0 → 1.6.1-alpha.0

Configuration Options

Git Configuration

json

{
  "git": {
    "requireCleanWorkingDir": false, // Allow uncommitted changes
    "requireUpstream": false, // Don't require remote branch
    "commit": true, // Commit version changes
    "tag": true, // Create Git tag
    "push": false, // Don't auto-push
    "commitMessage": "chore: release v${version}"
  }
}

NPM Configuration

json

{
  "npm": {
    "publish": false, // Don't publish to NPM
    "publishPath": ".", // Path to package.json
    "allowSameVersion": false // Prevent duplicate versions
  }
}

Plugins Configuration

json

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular", // Use Angular preset
      "infile": "CHANGELOG.md" // Output file
    },
    "@release-it/bumper": {
      "in": "package.json",
      "out": "package-lock.json"
    }
  }
}

Best Practices

1. Commit Messages

Use conventional commit format
Be clear and concise
Reference issues when applicable
Use present tense ("add" not "added")

2. Version Management

Release regularly
Keep changelog up to date
Use semantic versioning properly
Document breaking changes clearly

3. Release Process

Test thoroughly before releasing
Review generated changelog
Tag releases appropriately
Push tags with commits

4. Changelog

Keep automatic generation enabled
Review generated content
Add additional context if needed
Maintain consistency

Common Issues

Issue 1: Release Fails with "Working directory not clean"

Cause: Uncommitted changes in working directory

Solution:

bash

# Commit or stash changes
git add .
git commit -m "chore: update files"

# Or configure to allow uncommitted changes
# In package.json: "requireCleanWorkingDir": false

Issue 2: Wrong Version Bump

Cause: Incorrect commit message format

Solution:

bash

# Review commit messages
git log --oneline

# Amend last commit
git commit --amend -m "fix: correct commit message"

Issue 3: Changelog Not Updated

Cause: Plugin configuration issue

Solution:

bash

# Check plugin configuration
cat package.json | grep "@release-it/conventional-changelog"

# Reinstall dependencies
pnpm install

Version and Changelog Management ​

What is Release-it ​

Quick Start ​

1. View Existing Configuration ​

2. Create a Release ​

3. Release Process ​

Version Types ​

Patch (Patch Version) ​

Minor (Minor Version) ​

Major (Major Version) ​

Project Configuration ​

package.json ​

Workflow ​

1. Develop New Features ​

2. Commit Message Format ​

3. Create a Release ​

4. Review and Push ​

Changelog Format ​

Auto-generated Changelog ​

Commit Message Types ​

Release Strategy ​

Manual Release ​

Interactive Release ​

Pre-release ​

Configuration Options ​

Git Configuration ​

NPM Configuration ​

Plugins Configuration ​

Best Practices ​

1. Commit Messages ​

2. Version Management ​

3. Release Process ​

4. Changelog ​

Common Issues ​

Issue 1: Release Fails with "Working directory not clean" ​

Issue 2: Wrong Version Bump ​

Issue 3: Changelog Not Updated ​

Related Resources ​

Version and Changelog Management

What is Release-it

Quick Start

1. View Existing Configuration

2. Create a Release

3. Release Process

Version Types

Patch (Patch Version)

Minor (Minor Version)

Major (Major Version)

Project Configuration

package.json

Workflow

1. Develop New Features

2. Commit Message Format

3. Create a Release

4. Review and Push

Changelog Format

Auto-generated Changelog

Commit Message Types

Release Strategy

Manual Release

Interactive Release

Pre-release

Configuration Options

Git Configuration

NPM Configuration

Plugins Configuration

Best Practices

1. Commit Messages

2. Version Management

3. Release Process

4. Changelog

Common Issues

Issue 1: Release Fails with "Working directory not clean"

Issue 2: Wrong Version Bump

Issue 3: Changelog Not Updated

Related Resources