FCAT

Appearance

Conventional Commits 和 standard-version 是两个与 Git 提交消息和版本管理相关的工具，但它们的功能和用途有所不同。以下是它们的区别和联系：

1. Conventional Commits ​

1.1 定义 ​

Conventional Commits 是一种 提交消息规范，它定义了一种标准化的 Git 提交消息格式，便于自动化工具解析提交历史并生成变更日志

1.2 提交消息格式 ​

<类型>(<范围>): <描述>

[可选正文]

[可选脚注]
<类型>(<范围>): <描述>

[可选正文]

[可选脚注]
  • 类型：如 feat（新功能）、fix（修复 bug）、docs（文档更新）等。
  • 范围：可选，表示影响的范围（如模块或文件）。
  • 描述：简洁明了地描述提交内容。
  • 正文：可选，提供更详细的说明。
  • 脚注：可选，用于关联 Issue 或标记破坏性变更。

示例：

feat(user): 添加用户登录功能

Closes #123
feat(user): 添加用户登录功能

Closes #123

1.3 作用 ​

  • 提高提交消息的可读性和一致性。
  • 便于自动化工具解析提交历史，生成变更日志或版本号。

2. standard-version ​

2.1 定义 ​

standard-version 是一个 自动化版本管理工具，它基于 Conventional Commits 规范，自动完成以下任务：

  1. 根据提交历史生成变更日志（CHANGELOG.md）。
  2. 根据提交类型（如 feat 或 fix）自动递增版本号。
  3. 创建 Git 标签（Tag）并提交变更。

2.2 功能 ​

  • 版本号管理：
    • feat 提交：递增次版本号（Minor）。
    • fix 提交：递增修订号（Patch）。
    • 包含 BREAKING CHANGE 的提交：递增主版本号（Major）。
  • 变更日志生成：
    • 根据提交消息自动生成 CHANGELOG.md。
  • Git 标签：
    • 自动创建版本标签（如 v1.2.3）。

2.3 使用示例 ​

  1. 安装 standard-version：

    bash
    npm install --save-dev standard-version
    npm install --save-dev standard-version

  2. 在 package.json 中添加脚本：

    json
    "scripts": {
  "release": "standard-version"
}
    "scripts": {
  "release": "standard-version"
}

  3. 运行发布命令：

    bash
    npm run release
    npm run release

3. 区别与联系 ​

3.1 区别 ​

特性Conventional Commitsstandard-version
用途提交消息规范自动化版本管理工具
功能定义提交消息格式生成变更日志、递增版本号、创建标签
依赖关系不依赖其他工具依赖 Conventional Commits 规范
使用场景提交代码时遵循规范发布版本时自动化流程

3.2 联系 ​

  • standard-version 是基于 Conventional Commits 规范的工具。
  • Conventional Commits 提供了提交消息的标准化格式，standard-version 利用这些格式来自动化版本管理。

4. 结合使用 ​

4.1 工作流程 ​

  1. 开发阶段：

    • 开发者遵循 Conventional Commits 规范提交代码。
    • 示例提交：
      bash
      git commit -m "feat(user): 添加用户登录功能"
git commit -m "fix(auth): 修复登录失败的问题"
      git commit -m "feat(user): 添加用户登录功能"
git commit -m "fix(auth): 修复登录失败的问题"

  2. 发布阶段：

    • 运行 standard-version 自动生成变更日志、递增版本号并创建标签。
    • 示例命令：
      bash
      npm run release
      npm run release

  3. 结果：

    • 生成 CHANGELOG.md 文件。
    • 更新 package.json 中的版本号。
    • 创建 Git 标签（如 v1.2.3）。

4.2 配置文件 ​

可以在 package.json 中配置 standard-version 的行为，例如：

json
"standard-version": {
  "skip": {
    "tag": false
  },
  "releaseCommitMessageFormat": "chore(release): {{currentTag}}"
}
"standard-version": {
  "skip": {
    "tag": false
  },
  "releaseCommitMessageFormat": "chore(release): {{currentTag}}"
}

5. 总结 ​

  • Conventional Commits 是一种提交消息规范，用于统一提交格式。
  • standard-version 是一个自动化工具，基于 Conventional Commits 规范，用于版本管理和变更日志生成。
  • 两者结合使用，可以实现从代码提交到版本发布的全流程自动化。

要在 Spring Boot 项目中使用 standard-version 来生成本地的 CHANGELOG.md 文件，需要以下步骤。standard-version 是一个自动化工具，用于根据 Git 提交消息生成变更日志，并根据语义版本控制（semver）规则自动版本发布。

1. 安装 Node.js 和 npm ​

standard-version 是一个 Node.js 工具，因此首先需要安装 Node.js 和 npm（Node 的包管理器）。你可以通过以下命令检查是否已经安装：

bash
node -v
npm -v
node -v
npm -v

如果尚未安装，请前往官网下载安装。

2. 初始化项目并安装 standard-version ​

在 Spring Boot 项目中，虽然我们主要使用 Java，但为了自动化管理版本和生成 CHANGELOG.md 文件，我们需要在项目中集成 standard-version。

  1. 进入项目根目录： 进入到你的 Spring Boot 项目的根目录。

  2. 初始化 npm 项目： 如果项目还没有 package.json 文件，可以运行以下命令来初始化：

bash
npm init -y
npm init -y
  1. 安装 standard-version： 在项目中安装 standard-version，将其作为开发依赖：
bash
npm install --save-dev standard-version
npm install --save-dev standard-version

3. 配置 standard-version ​

standard-version 会根据你的 Git 提交记录生成版本号和 CHANGELOG.md 文件。你可以在 package.json 中添加一些脚本来方便运行。

  1. 打开 package.json 文件。
  2. 在 scripts 部分添加一个 release 脚本：
json
"scripts": {
"release": "standard-version"
}
"scripts": {
"release": "standard-version"
}

这将使你能够使用 npm run release 命令来运行 standard-version。

4. 使用 Git 提交消息格式化 ​

standard-version 会根据语义化版本控制（Semantic Versioning）和 Git 提交消息的格式来生成 CHANGELOG.md。你需要遵循一定的提交消息格式。

以下是标准的提交消息格式：

  • feat: 用于增加新特性
  • fix: 用于修复 bug
  • docs: 用于文档更改
  • chore: 用于不影响代码的变动（例如依赖更新、工具配置等）
  • style: 用于代码风格修复（空格、缩进、逗号等格式）
  • refactor: 用于重构代码（没有新增功能或修复 bug）
  • test: 用于添加缺失的测试或修复已有测试

例如：

bash
git commit -m "feat: add login functionality"
git commit -m "fix: resolve null pointer exception"
git commit -m "chore: update dependencies"
git commit -m "feat: add login functionality"
git commit -m "fix: resolve null pointer exception"
git commit -m "chore: update dependencies"

重大变更，提交格式

feat(基础模块重构): 重构数据存储模块
BREAKING CHANGE: 数据存储接口改变，需要用户重新配置连接设置。
feat(基础模块重构): 重构数据存储模块
BREAKING CHANGE: 数据存储接口改变，需要用户重新配置连接设置。

5. 运行 standard-version 生成 CHANGELOG.md ​

在每次版本发布时，执行以下命令：

bash
npm run release
npm run release

该命令会根据 Git 提交记录自动生成一个新的版本号，并更新 CHANGELOG.md 文件。生成的版本号遵循语义版本控制规则（如：v1.0.1、v2.0.0）。同时，CHANGELOG.md 文件会被更新，格式如下：

markdown
# Changelog

## [1.1.0] - 2025-03-04
### Added
- feat: add login functionality

### Fixed
- fix: resolve null pointer exception

## [1.0.0] - 2025-02-20
### Added
- Initial release
# Changelog

## [1.1.0] - 2025-03-04
### Added
- feat: add login functionality

### Fixed
- fix: resolve null pointer exception

## [1.0.0] - 2025-02-20
### Added
- Initial release

6. 推送更改并发布 ​

在生成了新的版本和 CHANGELOG.md 文件之后，你可以推送更改到远程 Git 仓库：

bash
git push --follow-tags
git push --follow-tags

standard-version 会自动为你创建一个 Git 标签（tag），标记版本。

7. 测试过程的数据清理 ​

shell
PS D:\gitlab\ruoyi-vue> git tag
1.1.0
1.1.1
v1.2.3
v1.2.4
PS D:\gitlab\ruoyi-vue> git tag -d v1.2.3 v1.2.4
Deleted tag 'v1.2.3' (was 58244956)
Deleted tag 'v1.2.4' (was e23cd159)
PS D:\gitlab\ruoyi-vue> git tag
1.1.0
1.1.1
v1.2.3
v1.2.4
PS D:\gitlab\ruoyi-vue> git tag -d v1.2.3 v1.2.4
Deleted tag 'v1.2.3' (was 58244956)
Deleted tag 'v1.2.4' (was e23cd159)

8. 合并一个临时分支为一次提交 ​

shell
//创建临时分支，多次提交内容
git checkout -b temp-branch
//切换目标分支
git checkout <target-branch>
//合并临时分支，合并成一次提交
git merge --squash <temp-branch>
//删除临时分支
git branch -d temp-branch
//推送分支
git push --force
//创建临时分支，多次提交内容
git checkout -b temp-branch
//切换目标分支
git checkout <target-branch>
//合并临时分支，合并成一次提交
git merge --squash <temp-branch>
//删除临时分支
git branch -d temp-branch
//推送分支
git push --force

总结 ​

  • 通过 npm init -y 创建一个 package.json 文件。
  • 安装 standard-version：npm install --save-dev standard-version。
  • 在 package.json 中添加 release 脚本。
  • 提交消息遵循语义化版本控制规范。
  • 使用 npm run release 来自动生成版本号和更新 CHANGELOG.md。

如果使用 standard-version 后生成的 CHANGELOG.md 中的 URL 不正确，可能是由于 Git 远程仓库 URL 或 standard-version 配置问题。以下是排查和修复方法：

1. 检查 Git 远程仓库 URL ​

standard-version 默认会读取 Git 的远程仓库 URL（origin），确保它指向正确的 GitLab 地址：

bash
git remote -v
git remote -v

如果 URL 不正确，修改它：

bash
git remote set-url origin https://gitlab.com/your-username/your-repo.git
git remote set-url origin https://gitlab.com/your-username/your-repo.git

2. 确保 package.json 配置正确 ​

在 package.json 中，repository 和 standard-version 的 repositoryUrl 都要设置：

json
{
  "repository": {
    "type": "git",
    "url": "https://gitlab.com/your-username/your-repo.git"
  },
  "standard-version": {
    "repositoryUrl": "https://gitlab.com/your-username/your-repo.git"
  }
}
{
  "repository": {
    "type": "git",
    "url": "https://gitlab.com/your-username/your-repo.git"
  },
  "standard-version": {
    "repositoryUrl": "https://gitlab.com/your-username/your-repo.git"
  }
}

注意：

  • 如果 repositoryUrl 未设置，standard-version 会回退到 repository.url。
  • 如果仍然不正确，可能是 standard-version 版本问题，尝试升级：
    bash
    npm install standard-version@latest --save-dev
    npm install standard-version@latest --save-dev

3. 手动指定 issueUrlFormat 和 commitUrlFormat（可选） ​

如果 GitLab 的 URL 结构特殊（如自托管 GitLab），可以手动指定链接格式：

json
{
  "standard-version": {
    "repositoryUrl": "https://gitlab.com/your-username/your-repo",
    "issueUrlFormat": "https://gitlab.com/your-username/your-repo/issues/{{id}}",
    "commitUrlFormat": "https://gitlab.com/your-username/your-repo/commit/{{hash}}"
  }
}
{
  "standard-version": {
    "repositoryUrl": "https://gitlab.com/your-username/your-repo",
    "issueUrlFormat": "https://gitlab.com/your-username/your-repo/issues/{{id}}",
    "commitUrlFormat": "https://gitlab.com/your-username/your-repo/commit/{{hash}}"
  }
}

总结 ​

  1. 确保 Git 远程 URL 正确（git remote -v）。
  2. package.json 中配置 repository 和 standard-version.repositoryUrl。
  3. 强制指定 --repository-url（推荐）。
  4. 检查生成的 CHANGELOG.md 格式，必要时手动设置 issueUrlFormat 和 commitUrlFormat。

在 standard-version 中，BREAKING CHANGE 用于标记破坏性变更（Breaking Changes），通常指不向后兼容的 API 修改或重大更新。以下是具体操作方法：

1. 提交规范：在 Commit Message 中声明 Breaking Changes ​

方法一：使用 ! 标记（推荐） ​

在 feat 或 fix 类型后加 !，并在正文中写 BREAKING CHANGE:：

bash
git commit -m "feat!: 移除旧API" -m "BREAKING CHANGE: 旧API已废弃，请改用新API。"
git commit -m "feat!: 移除旧API" -m "BREAKING CHANGE: 旧API已废弃，请改用新API。"

或：

bash
git commit -m "fix(utils)!: 重构核心逻辑" -m "BREAKING CHANGE: 参数格式变更，不再支持旧格式。"
git commit -m "fix(utils)!: 重构核心逻辑" -m "BREAKING CHANGE: 参数格式变更，不再支持旧格式。"

方法二：纯正文声明 ​

如果不用 !，需在 commit 正文中明确写 BREAKING CHANGE:：

bash
git commit -m "feat: 新增配置系统" -m "BREAKING CHANGE: 旧配置文件格式不再兼容。"
git commit -m "feat: 新增配置系统" -m "BREAKING CHANGE: 旧配置文件格式不再兼容。"

2. 生成 CHANGELOG.md ​

运行 standard-version 后：

bash
npm run release
npm run release

生成的 CHANGELOG.md 会自动将 BREAKING CHANGE 归类到 Breaking Changes 章节，例如：

markdown
# Changelog

## [2.0.0](https://gitlab.com/your-repo/compare/v1.0.0...v2.0.0) (2023-01-01)

### ⚠ BREAKING CHANGES

* **旧API移除**: 旧API已废弃，请改用新API。
* **参数格式变更**: 不再支持旧格式。

### Features

* 新增配置系统 ([commit-hash](https://gitlab.com/your-repo/commit/xxx))
# Changelog

## [2.0.0](https://gitlab.com/your-repo/compare/v1.0.0...v2.0.0) (2023-01-01)

### ⚠ BREAKING CHANGES

* **旧API移除**: 旧API已废弃，请改用新API。
* **参数格式变更**: 不再支持旧格式。

### Features

* 新增配置系统 ([commit-hash](https://gitlab.com/your-repo/commit/xxx))

3. 版本号自动升级规则 ​

  • 如果 commit 包含 BREAKING CHANGE，standard-version 会：
    • 主版本号升级（MAJOR，如 1.0.0 → 2.0.0）。
    • 如果当前版本是 0.x.x，则升级次版本号（0.1.0 → 0.2.0）。

4. 验证 Breaking Changes ​

检查生成的版本号是否正确： ​

bash
git tag -l  # 查看最新版本号是否升级了 MAJOR
git tag -l  # 查看最新版本号是否升级了 MAJOR

检查 CHANGELOG.md： ​

确保 BREAKING CHANGES 章节已生成，且描述清晰。

5. 高级配置（可选） ​

在 package.json 中自定义 BREAKING CHANGE 的标题或格式：

json
{
  "standard-version": {
    "header": "Changelog",
    "breakingHeader": "🚨 Breaking Changes",
    "types": [
      { "type": "feat", "section": "Features" },
      { "type": "fix", "section": "Bug Fixes" }
    ]
  }
}
{
  "standard-version": {
    "header": "Changelog",
    "breakingHeader": "🚨 Breaking Changes",
    "types": [
      { "type": "feat", "section": "Features" },
      { "type": "fix", "section": "Bug Fixes" }
    ]
  }
}

常见问题 ​

Q1: 为什么 BREAKING CHANGE 没有触发版本升级？ ​

  • 确保 commit 信息格式正确（必须有 BREAKING CHANGE: 或 !）。
  • 检查 standard-version 版本（旧版本可能有 bug，建议使用最新版）。

Q2: 如何合并多个 Breaking Changes？ ​

在同一个版本中提交多个含 BREAKING CHANGE 的 commit，它们会被合并到同一章节。

总结 ​

  1. Commit 规范：用 ! 或 BREAKING CHANGE: 声明破坏性变更。
  2. 自动生成：standard-version 会归类到 Breaking Changes 并升级主版本号。
  3. 验证：检查 CHANGELOG.md 和版本号是否正确。

这样就能清晰地向用户传达不兼容变更！