FCAT | FCAT

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 规范，自动完成以下任务：

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

2.2 功能

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

2.3 使用示例

安装 standard-version：

bash

npm install --save-dev standard-version

npm install --save-dev standard-version

在 package.json 中添加脚本：

json

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

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

运行发布命令：
bash
```
npm run release
```
```
npm run release
```
1

3. 区别与联系

3.1 区别

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

3.2 联系

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

4. 结合使用

4.1 工作流程

开发阶段：

开发者遵循 Conventional Commits 规范提交代码。

示例提交：

bash

git commit -m "feat(user): 添加用户登录功能"
git commit -m "fix(auth): 修复登录失败的问题"

git commit -m "feat(user): 添加用户登录功能"
git commit -m "fix(auth): 修复登录失败的问题"

发布阶段：
- 运行 standard-version 自动生成变更日志、递增版本号并创建标签。
- 示例命令：
  bash
```
npm run release
```
```
npm run release
```
  1
结果：
- 生成 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。

进入项目根目录：进入到你的 Spring Boot 项目的根目录。
初始化 npm 项目：如果项目还没有 package.json 文件，可以运行以下命令来初始化：

bash

npm init -y

npm init -y

安装 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 中添加一些脚本来方便运行。

打开 package.json 文件。
在 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}}"
  }
}

总结

确保 Git 远程 URL 正确（git remote -v）。
package.json 中配置 repository 和 standard-version.repositoryUrl。
强制指定 --repository-url（推荐）。
检查生成的 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，它们会被合并到同一章节。

总结

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

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

1. Conventional Commits ​

1.1 定义 ​

1.2 提交消息格式 ​

1.3 作用 ​

2. standard-version ​

2.1 定义 ​

2.2 功能 ​

2.3 使用示例 ​

3. 区别与联系 ​

3.1 区别 ​

3.2 联系 ​

4. 结合使用 ​

4.1 工作流程 ​

4.2 配置文件 ​

5. 总结 ​

1. 安装 Node.js 和 npm ​

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

3. 配置 standard-version ​

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

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

6. 推送更改并发布 ​

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

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

总结 ​

1. 检查 Git 远程仓库 URL ​

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

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

总结 ​

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

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

方法二：纯正文声明 ​

2. 生成 CHANGELOG.md ​

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

4. 验证 Breaking Changes ​

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

检查 CHANGELOG.md： ​

5. 高级配置（可选） ​

常见问题 ​

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

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

总结 ​

1. Conventional Commits

1.1 定义

1.2 提交消息格式

1.3 作用

2. standard-version

2.1 定义

2.2 功能

2.3 使用示例

3. 区别与联系

3.1 区别

3.2 联系

4. 结合使用

4.1 工作流程

4.2 配置文件

5. 总结

1. 安装 Node.js 和 npm

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

3. 配置 `standard-version`

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

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

6. 推送更改并发布

7. 测试过程的数据清理

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

总结

1. 检查 Git 远程仓库 URL

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

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

总结

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

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

方法二：纯正文声明

2. 生成 CHANGELOG.md

3. 版本号自动升级规则

4. 验证 Breaking Changes

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

检查 `CHANGELOG.md`：

5. 高级配置（可选）

常见问题

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

Q2: 如何合并多个 Breaking Changes？

总结