✨ docs: 把提交信息规范固化成 CONTRIBUTING.md
约定 emoji 在行首、类型关键字与作用域用英文、描述用中文，并给出 10 种 类型的 emoji 与码位表。因为行首 emoji 会让 commitlint / semantic-release 这类工具读不到类型，规范里同时记录了两种应对方式。 顺手修掉 README 里一句会误导的话：本地 link: 安装时，profile 的 node_modules 可能是与源码同 inode 的硬链接副本，只刷新页面看不到改动。
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
# 提交信息规范
|
||||
|
||||
本仓库的提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 的结构，并在行首加一个 emoji 做视觉标记。**描述用中文**，类型关键字、作用域、脚注关键字保持英文。
|
||||
|
||||
## 格式
|
||||
|
||||
```text
|
||||
<emoji> <type>[(scope)][!]: <描述>
|
||||
<空行>
|
||||
[正文：为什么这么改、影响面、迁移注意事项]
|
||||
<空行>
|
||||
[脚注：Refs: #12 / Closes: #34 / BREAKING CHANGE: ...]
|
||||
```
|
||||
|
||||
- `<emoji>`：下面表格里该类型对应的 emoji，后面跟**一个空格**。
|
||||
- `<type>`：小写英文关键字，见下表。
|
||||
- `(scope)`：可选，改动范围。用 `()` 包住一个简短英文标识，例如 `docs(ci)`、`fix(client)`、`feat(host)`。
|
||||
- `!`：可选，紧跟在 type 或 scope 之后、冒号之前，表示破坏性变更。
|
||||
- `<描述>`：中文，一句话，讲清这次改动做了什么。**首行不超过 72 个字符**（中文字符按 2 个宽度算），结尾不加句号。
|
||||
- 正文：中文，每行不超过 72 个宽度。说清"为什么"，不要复述 diff。单行描述足以讲明白时就省略。
|
||||
- 脚注：破坏性变更必须写 `BREAKING CHANGE: <中文说明>`，不能只靠 `!`。
|
||||
|
||||
## 类型与 emoji
|
||||
|
||||
| 类型 | emoji | 码位 | 用途 |
|
||||
| --- | --- | --- | --- |
|
||||
| `feat` | ✨ | `U+2728` | 新增功能 |
|
||||
| `fix` | 🐛 | `U+1F41B` | 修复缺陷 |
|
||||
| `docs` | 📝 | `U+1F4DD` | 只改文档 |
|
||||
| `refactor` | ♻️ | `U+267B U+FE0F` | 重构，行为不变 |
|
||||
| `perf` | ⚡️ | `U+26A1 U+FE0F` | 性能优化 |
|
||||
| `test` | ✅ | `U+2705` | 变更测试 |
|
||||
| `build` | 📦️ | `U+1F4E6 U+FE0F` | 构建系统或依赖 |
|
||||
| `ci` | 💚 | `U+1F49A` | CI 配置 |
|
||||
| `chore` | 🔧 | `U+1F527` | 杂项，以上都不属于时用 |
|
||||
| `revert` | ⏪️ | `U+23EA U+FE0F` | 回滚某次提交，正文写 `Refs: <被回滚的提交>` |
|
||||
|
||||
**复制上表里的 emoji，不要手敲。** 带 `U+FE0F` 的那五个是「基础字符 + 变体选择符」两个码位，手敲时很容易只打出前一个字符；对工具来说 `♻`（`U+267B`）和 `♻️`（`U+267B U+FE0F`）是两个不同的字符串，比对会失败。写规范或写脚本时，比较 emoji 前先做一次 NFC 归一化，或把两边都按 `\uFE0F?` 处理。
|
||||
|
||||
## 示例
|
||||
|
||||
新增功能：
|
||||
|
||||
```text
|
||||
✨ feat(client): 会话行悬停区加删除按钮
|
||||
|
||||
官方 archive 与 pin 两个悬停按钮保持原位，本插件的删除按钮插在两者
|
||||
之间，不再借用 archive 的 id 压级替换。
|
||||
```
|
||||
|
||||
修复缺陷：
|
||||
|
||||
```text
|
||||
🐛 fix(host): 延迟删除台账只记录根会话
|
||||
|
||||
台账原先记录整棵树，但启动清扫以根为单位整棵删除，导致子会话被重复
|
||||
删除并重复广播 api-session/removed。
|
||||
```
|
||||
|
||||
破坏性变更：
|
||||
|
||||
```text
|
||||
♻️ refactor!: 行内按钮改用自己的槽位 id
|
||||
|
||||
BREAKING CHANGE: 悬停区布局变化，官方归档按钮回到原来的位置。按住旧
|
||||
结构写样式的用户需要调整。
|
||||
```
|
||||
|
||||
纯文档：
|
||||
|
||||
```text
|
||||
📝 docs: 安装说明改为只走 Git 标签与本地 tgz
|
||||
```
|
||||
|
||||
## 工具链提示
|
||||
|
||||
emoji 在行首是本仓库的有意选择，视觉上整齐。代价是：以类型前缀开头的解析工具（`commitlint`、`semantic-release`、`release-please` 等）会读不到类型。如果以后要接这类工具，有两条路：
|
||||
|
||||
1. 把 emoji 挪到冒号之后（`feat: ✨ 描述`），类型回到行首，规范其余部分不变；
|
||||
2. 保留行首 emoji，给工具写一个剥掉开头 emoji 与空格的预处理。可用的正则（`\p{Extended_Pictographic}` 已覆盖带与不带变体选择符两种写法）：
|
||||
|
||||
```text
|
||||
^(?:\p{Extended_Pictographic}\uFE0F?\s+)?(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s(?<desc>.+)$
|
||||
```
|
||||
|
||||
## 启用提交模板（可选）
|
||||
|
||||
`.gitmessage` 是提交信息模板。启用后每次 `git commit` 会带上前缀提示，删掉不需要的部分即可：
|
||||
|
||||
```bash
|
||||
git config commit.template .gitmessage
|
||||
```
|
||||
|
||||
模板里以 `#` 开头的行会被 git 自动丢弃，不会进入提交信息。只对当前仓库生效；换机器要重新执行一次。
|
||||
Reference in New Issue
Block a user