破坏性变更怎么标注
不兼容的改动必须让工具与下游用户都看得出来，否则版本号会被低估、升级会踩坑。Conventional Commits 提供两种写法：一是在 type 或 scope 后面加感叹号，例如 feat!、feat(api)!；二是在提交页脚写 BREAKING CHANGE: 加说明。两种写法都能被工具识别为破坏性变更，从而触发主版本号升级，区别在于页脚写法可以承载更长的迁移说明。
基本信息
| 方式一 | <type>! 或 <type>(<scope>)! 后跟冒号 |
|---|---|
| 方式二 | 页脚写 BREAKING CHANGE: <说明>，必须大写 |
| 位置 | 感叹号在类型或作用域之后、冒号之前 |
| 版本影响 | 按规范对应主版本号升级 |
| 平台 | 与托管平台无关，由提交信息驱动 |
典型使用场景
- 删除了对外接口或改变了返回结构
- 修改了配置项名称，老配置不再生效
- 升级依赖导致行为不兼容，需要调用方调整
- 改变默认行为（如默认开启强制跳转）
- 数据格式变更，需要下游迁移
- 提前在提交里写清迁移方式，减少升级沟通成本
示例
示例
git commit -m 'feat!: 默认开启强制 HTTPS' # 感叹号写法
git commit -m 'refactor(api)!: 统一返回结构包裹' # 带作用域的写法
# 页脚写法需要分两段
# git commit -m '标题' -m 'BREAKING CHANGE: 说明迁移方式'
git commit -m 'fix(db): 迁移时区处理' \
-m 'BREAKING CHANGE: 历史时间列将按 UTC 重写，需先执行迁移脚本'两种写法对比
| 写法 | 特点 |
|---|---|
| type! 加感叹号 | 简洁，适合一句话能说清的情况 |
| BREAKING CHANGE 页脚 | 可写多行说明，适合需要迁移步骤的改动 |
| 两者同时用 | 既能被工具快速识别，又保留详细说明 |
破坏性变更要在正文里写清迁移方式；只写感叹号而不说明影响面，会让下游升级受阻，等于把成本转嫁给使用者。