📝 docs: 规定提交信息只有标题不要正文与脚注
This commit is contained in:
+15
-30
@@ -1,28 +1,26 @@
|
||||
# 提交信息规范
|
||||
|
||||
本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域、脚注关键字保持英文。
|
||||
本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的**首行**结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域保持英文。
|
||||
|
||||
## 格式
|
||||
|
||||
提交信息分三段，除首行外都可省略：
|
||||
**一条提交信息只有一行**，没有正文，也没有脚注：
|
||||
|
||||
```text
|
||||
<emoji> <type>[(scope)][!]: <描述> ← 首行，必写，永远只有一行
|
||||
← 一个空行分隔（没有正文时连空行也不要）
|
||||
[正文：可多段多行，说清为什么这么改] ← 可选
|
||||
← 一个空行分隔（没有脚注时可省略）
|
||||
[脚注：Refs: / Closes: / BREAKING CHANGE:] ← 可选
|
||||
<emoji> <type>[(scope)][!]: <中文描述>
|
||||
```
|
||||
|
||||
- `<emoji>`：下面表格里该类型对应的 emoji，后面跟**一个空格**。emoji 是必需的，且必须与本行类型一致——`📝 docs:` 对，`✨ docs:` 不对。
|
||||
- `<type>`：小写英文关键字，见下表。
|
||||
- `(scope)`：可选，改动范围。用 `()` 包住一个简短英文标识，例如 `docs(ci)`、`fix(client)`、`feat(host)`。
|
||||
- `!`：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。
|
||||
- `<描述>`：中文，**一句话**，讲清这次改动做了什么；不换行、不用列表、不加句号。首行宽度不超过 72（中文字符按 2 个宽度算）。
|
||||
- 正文：可选，中文，可以多段多行，每行不超过 72 个宽度。写"为什么这么改""影响面""迁移要注意什么"，不要复述 diff。描述一句话讲得清时就不要写正文。
|
||||
- 脚注：可选（破坏性变更除外），关键字用英文。破坏性变更必须写 `BREAKING CHANGE: <中文说明>`，不能只靠 `!`。
|
||||
- `<描述>`：中文，一句话，讲清这次改动做了什么；不换行、不用列表、不加句号。宽度不超过 72（中文字符按 2 个宽度算）。
|
||||
|
||||
上面说的"单行"指的是**首行只有一行**（不用列表、不折行）——正文是另一回事，需要时就写，多写几段不算违规。别把两者混起来：没有正文是允许的，不是要求。
|
||||
**不要写正文，也不要写脚注。** 连 `Refs:` / `Closes:` / `BREAKING CHANGE:` 这类尾注也不写——需要交代的"为什么""影响面""迁移注意事项"，写进 [README.md](README.md) 或本文件，或写进代码注释，让说明跟着代码走，而不是埋在 `git log` 里。
|
||||
|
||||
**破坏性变更只靠 `!` 标记**（例如 `♻️ refactor!: …`）。这一条是对 Conventional Commits 的有意偏离：它要求破坏性变更必须有 `BREAKING CHANGE:` 脚注，本仓库不写脚注，所以判断破坏性变更以 `!` 为准。
|
||||
|
||||
如果确实需要多行说明，说明这次改动不该只用一个提交标题交代——先补文档，再提交。
|
||||
|
||||
## 类型与 emoji
|
||||
|
||||
@@ -43,35 +41,22 @@
|
||||
|
||||
## 示例
|
||||
|
||||
新增功能：
|
||||
每条都是一整条提交信息，就这一行：
|
||||
|
||||
```text
|
||||
✨ feat(client): 会话行悬停区加删除按钮
|
||||
|
||||
官方 archive 与 pin 两个悬停按钮保持原位，本插件的删除按钮插在两者
|
||||
之间，不再借用 archive 的 id 压级替换。
|
||||
```
|
||||
|
||||
修复缺陷：
|
||||
|
||||
```text
|
||||
🐛 fix(host): 延迟删除台账只记录根会话
|
||||
|
||||
台账原先记录整棵树，但启动清扫以根为单位整棵删除，导致子会话被重复
|
||||
删除并重复广播 api-session/removed。
|
||||
```
|
||||
|
||||
破坏性变更：
|
||||
带作用域与破坏性标记（破坏性变更**没有**脚注，只看 `!`）：
|
||||
|
||||
```text
|
||||
♻️ refactor!: 行内按钮改用自己的槽位 id
|
||||
|
||||
BREAKING CHANGE: 悬停区布局变化，官方归档按钮回到原来的位置。按住旧
|
||||
结构写样式的用户需要调整。
|
||||
♻️ refactor(client)!: 行内按钮改用自己的槽位 id
|
||||
```
|
||||
|
||||
纯文档：
|
||||
|
||||
```text
|
||||
📝 docs: 安装说明改为只走 Git 标签与本地 tgz
|
||||
```
|
||||
@@ -89,7 +74,7 @@ emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以
|
||||
|
||||
## 自查
|
||||
|
||||
`scripts/check-commit-log.mjs` 会按本规范检查现有提交的首行，只报告、不拦提交：
|
||||
`scripts/check-commit-log.mjs` 会按本规范检查现有提交，只报告、不拦提交。除了首行格式，它还会报出**任何带正文或脚注的提交**：
|
||||
|
||||
```bash
|
||||
node scripts/check-commit-log.mjs # 最近 10 条
|
||||
@@ -100,10 +85,10 @@ node scripts/check-commit-log.mjs all # 全部
|
||||
|
||||
## 启用提交模板（可选）
|
||||
|
||||
`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示，删掉不需要的部分即可：
|
||||
`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示：
|
||||
|
||||
```bash
|
||||
git config commit.template .gitmessage
|
||||
```
|
||||
|
||||
模板里以 `#` 开头的行会被 git 自动丢弃，不会进入提交信息。只对当前仓库生效；换机器要重新执行一次。
|
||||
模板整份都是 `#` 开头的注释，git 会自动丢弃，所以直接 `git commit -m` 也不受影响。只对当前仓库生效；换机器要重新执行一次。
|
||||
|
||||
Reference in New Issue
Block a user