csh/tsl-devkit
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3d83740f88b6aaba6962256be517656496b83f25
tsl-devkit/docs/common/commit_message.md
T
csh ac794a6a70 Squashed 'docs/standards/playbook/' changes from e504a68..b529012 
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
2026-01-08 15:56:36 +08:00

6.0 KiB
Raw Blame History

提交信息规范（Commit Messages）

提交信息用于清晰表达变更意图、范围和原因，便于回溯与自动化发布。

1. 目标

  • 让每次提交都能被独立理解。
  • 支持快速定位问题与版本回滚。
  • 可被工具解析（变更日志/发布流程）。

2. 格式

推荐使用以下结构（emoji 可选，但建议默认带上以便快速扫读）：

: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: 初始化/首次发布
feat ✨ :sparkles: 新功能
fix 🐛 :bug: Bug 修复
perf 🚀 :rocket: 性能优化
refactor ♻️ :recycle: 重构（行为不变）
style 🎨 :art: 代码样式/格式（行为不变）
docs 📝 :memo: 文档更新
test ✅ :white_check_mark: 测试新增/修正
deps 📦 :package: 依赖更新
security 🔒 :lock: 安全修复
deprecate ⚠️ :warning: 废弃/弃用标记
remove 🗑️ :wastebasket: 删除功能/代码
chore 🔧 :wrench: 构建/配置/工具/维护性改动
contrib 👥 :busts_in_silhouette: 贡献者/致谢相关
release 🔖 :bookmark: 发布/打版本标签

注：:white_check_mark: 为补充图例，用于 test 类型。

如需新增新的 type，必须同时补充对应 emoji 与说明。

5. 版本号规范（SemVer）

遵循语义化版本规范。

5.1 格式

MAJOR.MINOR.PATCH

5.2 字段说明

字段 说明 何时递增
MAJOR 主版本号 不兼容的 API 修改
MINOR 次版本号 向后兼容的功能新增
PATCH 修订号 向后兼容的问题修正

5.3 更新规则

  • MAJOR（主版本）：破坏性变更，不向后兼容。递增后 MINOR 和 PATCH 重置为 0。
  • MINOR（次版本）：新增功能但保持兼容。递增后 PATCH 重置为 0。
  • PATCH（修订）：仅修复 bug，不新增功能。

5.4 示例

1.0.0    # 首个稳定版
1.1.0    # 新增功能
1.1.1    # Bug 修复
2.0.0    # 破坏性变更

5.5 Pre-release 版本

1.0.0-alpha.1
1.0.0-beta
1.0.0-rc.1
1.0.0

5.6 初始开发阶段

0.1.0    # 初始版本
0.2.0    # API 未稳定
1.0.0    # 首个稳定版

注意：0.x.x 版本可以随时破坏兼容性。

6. 示例

带 emoji：

:sparkles: feat(order): add batch cancel api

support canceling multiple orders in one request; keep old api unchanged.

Refs: TSL-1234

不带 emoji：

refactor(order): simplify cancel flow
Reference in New Issue View Git Blame Copy Permalink