Semantic Versioning

语义化版本控制（SemVer）

Overview

概述

Establish semantic versioning practices to maintain consistent version numbering aligned with release significance, enabling automated version management and release notes generation.

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

When to Use

适用场景

Package and library releases
API versioning
Version bumping automation
Release note generation
Breaking change tracking
Dependency management
Changelog management

包与库发布
API版本控制
版本升级自动化
发布说明生成
破坏性变更追踪
依赖管理
变更日志管理

Implementation Examples

实现示例

1. Semantic Versioning Configuration

1. 语义化版本控制配置

yaml

undefined

yaml

undefined

package.json

{ "name": "my-awesome-package", "version": "1.2.3", "description": "An awesome package", "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" } }

undefined

{ "name": "my-awesome-package", "version": "1.2.3", "description": "An awesome package", "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" } }

undefined

2. Conventional Commits Format

2. 约定式提交格式

bash

undefined

bash

undefined

Feature commit (MINOR bump)

git commit -m "feat: add new search feature" git commit -m "feat(api): add pagination support"

Bug fix commit (PATCH bump)

git commit -m "fix: resolve null pointer exception" git commit -m "fix(auth): fix login timeout issue"

Breaking change (MAJOR bump)

git commit -m "feat!: redesign API endpoints" git commit -m "feat(api)!: remove deprecated methods"

Documentation

git commit -m "docs: update README"

Performance improvement

git commit -m "perf: optimize database queries"

Refactoring

git commit -m "refactor: simplify authentication logic"

Tests

git commit -m "test: add integration tests"

Chore

git commit -m "chore: update dependencies"

Complete example with body and footer

git commit -m "feat(payment): add Stripe integration

Add support for processing credit card payments via Stripe. Includes webhook handling for payment confirmations.

BREAKING CHANGE: Payment API endpoint changed from /pay to /api/v2/payments Closes #123"

undefined

git commit -m "feat(payment): add Stripe integration

Add support for processing credit card payments via Stripe. Includes webhook handling for payment confirmations.

BREAKING CHANGE: Payment API endpoint changed from /pay to /api/v2/payments Closes #123"

undefined

3. Semantic Release Configuration

3. Semantic Release配置

javascript

// 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'
  ]
};

javascript

// 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. Version Bumping Script

4. 版本升级脚本

bash

#!/bin/bash

bash

#!/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"

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"

undefined

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"

undefined

5. Changelog Generation

5. 变更日志生成

bash

#!/bin/bash

bash

#!/bin/bash

generate-changelog.sh

Using conventional-changelog CLI

conventional-changelog -p angular -i CHANGELOG.md -s

Or manually format changelog

CHANGELOG="# Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

CHANGELOG="# Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

New feature description

New feature description

Changed

Changed feature description

Changed feature description

Deprecated

Deprecated feature description

Deprecated feature description

Removed

Removed feature description

Removed feature description

Fixed

Bug fix description

Bug fix description

Security

Security fix description

Security fix description

[1.2.0] - 2024-01-15

Added

New search functionality
Support for pagination

New search functionality
Support for pagination

Fixed

Critical security vulnerability in authentication
Memory leak in cache manager"

echo "$CHANGELOG" > CHANGELOG.md

undefined

Critical security vulnerability in authentication
Memory leak in cache manager"

echo "$CHANGELOG" > CHANGELOG.md

undefined

6. GitHub Actions Release Workflow

6. GitHub Actions发布工作流

yaml

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 }}

yaml

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 }}

Best Practices

最佳实践

✅ DO

✅ 推荐做法

Follow strict MAJOR.MINOR.PATCH format
Use conventional commits
Automate version bumping
Generate changelogs automatically
Tag releases in git
Document breaking changes
Use prerelease versions for testing

严格遵循MAJOR.MINOR.PATCH格式
使用约定式提交
自动化版本升级
自动生成变更日志
在Git中标记发布版本
记录破坏性变更
使用预发布版本进行测试

❌ DON'T

❌ 不推荐做法

Manually bump versions inconsistently
Skip breaking change documentation
Use arbitrary version numbering
Mix features in patch releases

不一致地手动升级版本
跳过破坏性变更的文档记录
使用任意版本编号方式
在补丁发布中混入新功能

Version Examples

版本示例

1.0.0 → First release
1.1.0 → New feature
1.1.1 → Bug fix
2.0.0 → Breaking changes
2.0.0-beta.1 → Beta

1.0.0 → 首次发布
1.1.0 → 新增功能
1.1.1 → 修复Bug
2.0.0 → 破坏性变更
2.0.0-beta.1 → Beta版本

semantic-versioning

Original

Translation

Semantic Versioning

语义化版本控制（SemVer）

Overview

概述

When to Use

适用场景

Implementation Examples

实现示例

1. Semantic Versioning Configuration

1. 语义化版本控制配置

package.json

package.json

2. Conventional Commits Format

2. 约定式提交格式

Feature commit (MINOR bump)

Feature commit (MINOR bump)

Bug fix commit (PATCH bump)

Bug fix commit (PATCH bump)

Breaking change (MAJOR bump)

Breaking change (MAJOR bump)

Documentation

Documentation

Performance improvement

Performance improvement

Refactoring

Refactoring

Tests

Tests

Chore

Chore

Complete example with body and footer

Complete example with body and footer

3. Semantic Release Configuration

3. Semantic Release配置

4. Version Bumping Script

4. 版本升级脚本

bump-version.sh

bump-version.sh

Update package.json

Update package.json

Update CHANGELOG

Update CHANGELOG

Commit and tag

Commit and tag

5. Changelog Generation

5. 变更日志生成

generate-changelog.sh

generate-changelog.sh

Using conventional-changelog CLI

Using conventional-changelog CLI

Or manually format changelog

Or manually format changelog

[Unreleased]

[Unreleased]

Added

Added

Changed

Changed

Deprecated

Deprecated

Removed

Removed

Fixed

Fixed

Security

Security

[1.2.0] - 2024-01-15

[1.2.0] - 2024-01-15

Added

Added

Fixed

Fixed

6. GitHub Actions Release Workflow

6. GitHub Actions发布工作流

Best Practices

最佳实践

✅ DO