语义版本控制

概览

建立语义版本控制实践，以保持与发布重要性一致的版本编号，实现自动化版本管理和生成发布说明。

何时使用

• 包和库的发布
• API版本控制
• 版本号自动化提升
• 发布说明生成
• 重大变更跟踪
• 依赖管理
• 变更日志管理

实施示例

1. 语义版本控制配置

# package.json
{
  "name": "my-awesome-package",
  "version": "1.2.3",
  "description": "一个很棒的包",
  "main": "dist/index.js",
  "repository": {
    "type": "git",
    "url": "https://github.com/org/repo.git"
  },
  "scripts": {
    "release": "semantic-release"
  },
  "devDependencies": {
    "semantic-release": "^21.0.0",
    "@semantic-release/changelog": "^6.0.0",
    "@semantic-release/git": "^10.0.0",
    "@semantic-release/github": "^9.0.0",
    "conventional-changelog-cli": "^3.0.0"
  }
}

2. 约定提交格式

# 特性提交（次要版本提升）
git commit -m "feat: 添加新的搜索功能"
git commit -m "feat(api): 添加分页支持"

# 缺陷修复提交（补丁版本提升）
git commit -m "fix: 解决空指针异常"
git commit -m "fix(auth): 修复登录超时问题"

# 重大变更（主版本提升）
git commit -m "feat!: 重新设计API端点"
git commit -m "feat(api)!: 移除弃用的方法"

# 文档
git commit -m "docs: 更新README"

# 性能改进
git commit -m "perf: 优化数据库查询"

# 重构
git commit -m "refactor: 简化认证逻辑"

# 测试
git commit -m "test: 添加集成测试"

# 杂项
git commit -m "chore: 更新依赖"

# 完整示例，带主体和页脚
git commit -m "feat(payment): 添加Stripe集成

添加通过Stripe处理信用卡支付的支持。
包括用于支付确认的Webhook处理。

BREAKING CHANGE: 支付API端点从/pay更改为/api/v2/payments
Closes #123"

3. 语义发布配置

// release.config.js
module.exports = {
  branches: ['main', {name: 'develop', prerelease: 'beta'}],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    '@semantic-release/changelog',
    '@semantic-release/git',
    '@semantic-release/github',
    '@semantic-release/npm'
  ]
};

4. 版本提升脚本

#!/bin/bash
# bump-version.sh

CURRENT_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": "\([^"]*\)".*/\1/')
IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"

case "${1:-patch}" in
  major)
    NEW_VERSION="$((MAJOR + 1)).0.0"
    ;;
  minor)
    NEW_VERSION="$MAJOR.$((MINOR + 1)).0"
    ;;
  patch)
    NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
    ;;
  *)
    echo "Usage: $0 {major|minor|patch}"
    exit 1
    ;;
esac

echo "Bumping version from $CURRENT_VERSION to $NEW_VERSION"

# Update package.json
npm version $NEW_VERSION --no-git-tag-v

# Update CHANGELOG
CHANGELOG_HEADER="## [$NEW_VERSION] - $(date +%Y-%m-%d)"
sed -i "1i\\$CHANGELOG_HEADER" CHANGELOG.md

# Commit and tag
git add package.json CHANGELOG.md package-lock.json
git commit -m "chore(release): version $NEW_VERSION"
git tag -a "v$NEW_VERSION" -m "Release $NEW_VERSION"

echo "✅ Version bumped to $NEW_VERSION"

5. 变更日志生成

#!/bin/bash
# generate-changelog.sh

# 使用conventional-changelog CLI
conventional-changelog -p angular -i CHANGELOG.md -s

# 或手动格式化变更日志
CHANGELOG="# Changelog

所有重要的项目变更都将记录在此文件中。

格式基于[Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
并且此项目遵循[语义版本控制](https://semver.org/spec/v2.0.0.html)。

## [Unreleased]

### Added
- 新功能描述

### Changed
- 更改功能描述

### Deprecated
- 弃用功能描述

### Removed
- 移除功能描述

### Fixed
- 缺陷修复描述

### Security
- 安全修复描述

## [1.2.0] - 2024-01-15

### Added
- 新搜索功能
- 支持分页

### Fixed
- 认证中的关键安全漏洞
- 缓存管理中的内存泄漏"

echo "$CHANGELOG" > CHANGELOG.md

6. GitHub Actions发布工作流

name: Semantic Release
on: [push, workflow_dispatch]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run build
      - uses: cycjimmy/semantic-release-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

最佳实践

✅ DO

• 遵循严格的主版本.次版本.补丁版本格式
• 使用约定提交
• 自动化版本提升
• 自动生成变更日志
• 在git中标记发布
• 文档化重大变更
• 使用预发布版本进行测试

❌ DON’T

• 手动不一致地提升版本
• 跳过重大变更文档
• 使用任意版本编号
• 在补丁发布中混合功能

版本示例

1.0.0 → 第一次发布
1.1.0 → 新功能
1.1.1 → 缺陷修复
2.0.0 → 重大变更
2.0.0-beta.1 → 测试版

资源

• 语义版本控制
• 约定提交