csh
ac794a6a70
b529012 ✅ test(tests): avoid hardcoded missing path 07583c8 🐛 fix(tests): make doc link check awk-portable 6244aa3 🔧 chore(ci): relax gitattributes check 31dd0c5 🐛 fix(scripts): require existing project root 15d4d63 🔧 chore(ci): install python3-pip 90c6313 🔧 chore(ci): run tests in a single job d84eff0 🔧 chore(ci): make actions base url configurable 395598d 🔧 chore(ci): fix yaml step names 4ae2733 ✨ feat(sync_standards): auto-detect existing languages e97fb00 ✨ feat(sync_standards): default gitattributes to append da0ef2b ✅ test: add automated tests and ci workflow 99bef30 🎨 style(markdown): format all markdown files with prettier 7e96bc8 ♻️ refactor(tsl): split function.md into 44 modular files 0d6b2a0 📝 docs(readme): add quick decision table and TL;DR for distribution methods 3b2188f 🎨 style(markdown): format markdown files with prettier 41fc43b 📝 docs(tsl): document {Unit.}Type source annotation 3dceaf7 📝 docs(tsl): clarify tsf-only top-level rules and type annotations 3a63829 📝 docs(skills): add create-plan skill f02a707 🐛 fix(scripts): escape markdown backticks in vendor_playbook 064aa92 🐛 fix(scripts): correct bat scripts 4881feb 🔧 chore(gitattributes): enforce crlf for bat files 1fa3e2a 🐛 fix(scripts): escape parentheses in sync_standards output 3958cad 📝 docs(vendor_playbook): mention ci templates 9d059cf ✨ feat(templates): add gitea ci example a52bb24 📝 docs(codex_skills): normalize markdown formatting cc8ad4c 📝 docs(skills): slim commit-message 2a98e15 🐛 fix(skills): quote YAML descriptions 8f78d22 🐛 fix(sync_standards): generate minimal AGENTS.md 5547665 ✨ feat(skills): add commit-message suggestion skill 3fe8bd7 🔧 chore(sync_standards): create AGENTS.md on sync 283d311 ✨ feat(playbook): add syntax book and codex skills tooling 5b97ed5 📝 docs(tsl): clarify syntax references 27e0700 ✨ feat(skills): add pdf/docx/pptx/xlsx wrapper workflows 5551363 ✨ feat(skills): add debugging and bulk refactor workflows 1d4f548 ✨ feat(skills): add built-in workflow skills c0895dd 📝 docs(skills): add anthropics document-skills integration cf9f80d 🔧 chore(playbook): add Claude Code skills guide and align python templates git-subtree-dir: docs/standards/playbook git-subtree-split: b529012c59c5d67c3073884d7b617763647417fd
164 lines
6.0 KiB
Markdown
164 lines
6.0 KiB
Markdown
# 提交信息规范（Commit Messages）
|
||
|
||
提交信息用于清晰表达变更意图、范围和原因，便于回溯与自动化发布。
|
||
|
||
## 1. 目标
|
||
|
||
- 让每次提交都能被独立理解。
|
||
- 支持快速定位问题与版本回滚。
|
||
- 可被工具解析（变更日志/发布流程）。
|
||
|
||
## 2. 格式
|
||
|
||
推荐使用以下结构（emoji 可选，但建议默认带上以便快速扫读）：
|
||
|
||
```txt
|
||
:emoji: type(scope): subject
|
||
|
||
body
|
||
|
||
footer
|
||
```
|
||
|
||
- `emoji`：可选，位于首行行首；若使用，必须与 `type`
|
||
一一对应（见 4）。为保持一致性，建议默认使用 emoji；若不使用则省略即可。
|
||
- `type`：变更类型，必须从 4 的对应表中选取。
|
||
- `scope`：可选，业务域/组件名（`lower_snake_case`），用于辅助定位影响范围。
|
||
- `subject`：一句话概述，使用祈使句/现在时，首字母小写，不加句号。
|
||
- `body`：可选，说明动机、关键实现、影响面；每行建议 ≤ 72 字符。
|
||
- `footer`：可选，关联任务/缺陷号，或 `BREAKING CHANGE:` 说明不兼容变更。
|
||
|
||
不使用 emoji 时，首行直接写 `type(scope): subject` 即可。
|
||
|
||
## 3. 约定
|
||
|
||
### 3.1 一次提交的边界
|
||
|
||
- 一个提交对应一个**逻辑变更**，而不是一个文件或一个模块。
|
||
- 可以同时修改多个 `unit/class/function`，只要它们属于同一逻辑变更。
|
||
- **允许合并的情况**：联动修改是变更所必需的同步/适配（不一起提会导致编译失败、测试失败或行为不一致）。
|
||
- 例：改了 A 的接口签名，同时更新 B 的调用点。
|
||
- **应当拆分的情况**：改动彼此独立，仅是“顺手优化/无关重构/额外功能”。
|
||
- 例：在修复 A 的 bug 时顺便重构 B 的内部实现。
|
||
- 实用判断：
|
||
1. 这次提交能用一句话概括吗？若需要两句话，考虑拆分。
|
||
2. 若只回滚其中一部分，系统还能保持正确吗？不能则不拆。
|
||
3. 每个提交是否都能保持可运行/可构建/测试不更坏？做不到则合并。
|
||
|
||
### 3.2 大模块重构的提交拆分
|
||
|
||
当重构整个模块并影响到其他模块时，建议按“可回滚的小步”拆分提交：
|
||
|
||
1. **前置整理**：仅做无行为影响的清理（重命名、抽函数、补注释/类型、补测试）。
|
||
2. **核心重构**：在模块内部做结构调整，尽量保持对外接口不变；必要时加适配层。
|
||
3. **迁移调用方**：逐步把其他模块迁移到新接口/新行为上。
|
||
4. **清理旧接口**：确认无人使用后再删除适配层/旧代码。
|
||
|
||
若重构为破坏性变更，优先采用“两阶段”：先引入新接口并兼容旧接口（deprecated），迁移完成后再删除旧接口。
|
||
|
||
### 3.3 其他约定
|
||
|
||
- `subject` 尽量 ≤ 72 字符；必要时用 `body` 补充细节。
|
||
- `body/footer` 说明“为什么改、影响什么”，而不是复述代码。
|
||
|
||
## 4. 提交类型与 Emoji 对应
|
||
|
||
本仓库采用固定的
|
||
`type`/emoji 一一对应关系；使用 emoji 时必须使用对应的那一个，不得错配。
|
||
|
||
| type | emoji（预览 / 代码） | 说明 |
|
||
| ----------- | --------------------------------------------- | ------------------------- |
|
||
| `init` | :tada: `:tada:` | 初始化/首次发布 |
|
||
| `feat` | :sparkles: `:sparkles:` | 新功能 |
|
||
| `fix` | :bug: `:bug:` | Bug 修复 |
|
||
| `perf` | :rocket: `:rocket:` | 性能优化 |
|
||
| `refactor` | :recycle: `:recycle:` | 重构（行为不变） |
|
||
| `style` | :art: `:art:` | 代码样式/格式（行为不变） |
|
||
| `docs` | :memo: `:memo:` | 文档更新 |
|
||
| `test` | :white_check_mark: `:white_check_mark:` | 测试新增/修正 |
|
||
| `deps` | :package: `:package:` | 依赖更新 |
|
||
| `security` | :lock: `:lock:` | 安全修复 |
|
||
| `deprecate` | :warning: `:warning:` | 废弃/弃用标记 |
|
||
| `remove` | :wastebasket: `:wastebasket:` | 删除功能/代码 |
|
||
| `chore` | :wrench: `:wrench:` | 构建/配置/工具/维护性改动 |
|
||
| `contrib` | :busts_in_silhouette: `:busts_in_silhouette:` | 贡献者/致谢相关 |
|
||
| `release` | :bookmark: `:bookmark:` | 发布/打版本标签 |
|
||
|
||
注：`:white_check_mark:` 为补充图例，用于 `test` 类型。
|
||
|
||
如需新增新的 `type`，必须同时补充对应 emoji 与说明。
|
||
|
||
---
|
||
|
||
## 5. 版本号规范（SemVer）
|
||
|
||
遵循语义化版本规范。
|
||
|
||
### 5.1 格式
|
||
|
||
```txt
|
||
MAJOR.MINOR.PATCH
|
||
```
|
||
|
||
### 5.2 字段说明
|
||
|
||
| 字段 | 说明 | 何时递增 |
|
||
| --------- | -------- | ------------------ |
|
||
| **MAJOR** | 主版本号 | 不兼容的 API 修改 |
|
||
| **MINOR** | 次版本号 | 向后兼容的功能新增 |
|
||
| **PATCH** | 修订号 | 向后兼容的问题修正 |
|
||
|
||
### 5.3 更新规则
|
||
|
||
- **MAJOR（主版本）**：破坏性变更，不向后兼容。递增后 MINOR 和 PATCH 重置为 0。
|
||
- **MINOR（次版本）**：新增功能但保持兼容。递增后 PATCH 重置为 0。
|
||
- **PATCH（修订）**：仅修复 bug，不新增功能。
|
||
|
||
### 5.4 示例
|
||
|
||
```txt
|
||
1.0.0 # 首个稳定版
|
||
1.1.0 # 新增功能
|
||
1.1.1 # Bug 修复
|
||
2.0.0 # 破坏性变更
|
||
```
|
||
|
||
### 5.5 Pre-release 版本
|
||
|
||
```txt
|
||
1.0.0-alpha.1
|
||
1.0.0-beta
|
||
1.0.0-rc.1
|
||
1.0.0
|
||
```
|
||
|
||
### 5.6 初始开发阶段
|
||
|
||
```txt
|
||
0.1.0 # 初始版本
|
||
0.2.0 # API 未稳定
|
||
1.0.0 # 首个稳定版
|
||
```
|
||
|
||
注意：`0.x.x` 版本可以随时破坏兼容性。
|
||
|
||
---
|
||
|
||
## 6. 示例
|
||
|
||
带 emoji：
|
||
|
||
```txt
|
||
:sparkles: feat(order): add batch cancel api
|
||
|
||
support canceling multiple orders in one request; keep old api unchanged.
|
||
|
||
Refs: TSL-1234
|
||
```
|
||
|
||
不带 emoji：
|
||
|
||
```txt
|
||
refactor(order): simplify cancel flow
|
||
```
|