|
|
@@ -0,0 +1,99 @@
|
|
|
+# Commit Message 规范
|
|
|
+
|
|
|
+参考 [Angular 规范](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
|
|
|
+（阮一峰 [《Commit message 和 Change log 编写指南》](https://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html)），
|
|
|
+结合本仓库实际情况本地化。纯约定，无工具强制——提交前自查。
|
|
|
+
|
|
|
+## 格式
|
|
|
+
|
|
|
+```
|
|
|
+<type>(<scope>): <subject>
|
|
|
+// 空一行
|
|
|
+<body>
|
|
|
+// 空一行
|
|
|
+<footer>
|
|
|
+```
|
|
|
+
|
|
|
+Header 必需；Body / Footer 可省略。**任何一行不超过 72 显示列**
|
|
|
+（中文按双宽计，约 24~36 个汉字；此约束针对 commit message，
|
|
|
+markdown 文档本身不受限），避免自动换行破坏格式。
|
|
|
+
|
|
|
+## Header
|
|
|
+
|
|
|
+### type（必需）
|
|
|
+
|
|
|
+| type | 用途 | 进 Change log |
|
|
|
+| --- | --- | --- |
|
|
|
+| `feat` | 新功能 | 是 |
|
|
|
+| `fix` | 修 bug | 是 |
|
|
|
+| `docs` | 仅文档变动 | 否 |
|
|
|
+| `style` | 格式调整（不影响代码运行：空格、格式、标点） | 否 |
|
|
|
+| `refactor` | 既非新增功能、也非修 bug 的代码变动 | 否 |
|
|
|
+| `test` | 增加或修改测试 | 否 |
|
|
|
+| `chore` | 构建过程或辅助工具的变动 | 否 |
|
|
|
+| `perf` | 性能优化（Angular 后续补充，本仓库已在使用） | 建议 |
|
|
|
+
|
|
|
+- `revert` 特殊格式：以 `revert: ` 开头，后跟被撤销 commit 的 Header；
|
|
|
+ Body 固定写 `This reverts commit <hash>.`
|
|
|
+
|
|
|
+### scope（可选）
|
|
|
+
|
|
|
+影响的范围，用模块/包名，如 `text`、`audio`、`renderer`、`core`、`collect`、
|
|
|
+`tts`、`shared`、`templates`、`deploy`（Docker/配置/部署）、`web`、`cli`。
|
|
|
+跨多个模块时可省略 scope 或用主导模块名，不要罗列一长串。
|
|
|
+
|
|
|
+### subject（必需）
|
|
|
+
|
|
|
+- **不超过 50 字符**（约 17~25 个汉字）。细节一律下沉到 Body，标题保持一行可读。
|
|
|
+- 以动词开头，第一人称现在时（"新增"而非"新增了"），结尾不加句号。
|
|
|
+- 现有提交常用「主题——要点」破折号补充形式；若要点放不下标题，移入 Body。
|
|
|
+
|
|
|
+## Body
|
|
|
+
|
|
|
+- 分点列出改动时，**每条先写动机与新旧行为对比**，再写做法——说明"为什么改"
|
|
|
+ 比罗列"改了什么"更重要：
|
|
|
+ - 差：「CLI/web 客户端只透传」
|
|
|
+ - 好：「模型解析收敛到 core 一处（原 CLI/web 各自合并兜底，行为不一致且
|
|
|
+ 静默回退到硬编码旧模型）；现在未配置显式报错，快速失败」
|
|
|
+- 接口/契约变更、删除的兜底逻辑等**行为变更**必须显式写出旧行为。
|
|
|
+
|
|
|
+## Footer
|
|
|
+
|
|
|
+只用于两种情况：
|
|
|
+
|
|
|
+1. **不兼容变动**：以 `BREAKING CHANGE:` 开头，说明变动内容、理由、迁移方法：
|
|
|
+
|
|
|
+ ```
|
|
|
+ BREAKING CHANGE: DocumentRunConfig.llm.model 改为可选。
|
|
|
+
|
|
|
+ 迁移：调用方不再需要自行兜底默认模型；runDocument 在三者均未设置时抛错。
|
|
|
+ ```
|
|
|
+
|
|
|
+2. **关闭 Issue**：`Closes #234`，多个用逗号分隔。
|
|
|
+
|
|
|
+此外允许追加 `Co-Authored-By: ...` trailer（git 惯例，注明协作生成方），
|
|
|
+放在上述条目之后。
|
|
|
+
|
|
|
+## 示例
|
|
|
+
|
|
|
+```
|
|
|
+feat(core): LLM 模型三级解析
|
|
|
+
|
|
|
+模型解析收敛到 core runDocument 一处：--llm-model > LLM_MODEL env >
|
|
|
+config.llm.model。原来 CLI 与 web 各自合并兜底（硬编码 gpt-4o/glm-5.1），
|
|
|
+配置缺失时静默降级到过期模型；现在未配置直接报错，容器部署可仅注入
|
|
|
+LLM_MODEL 切换模型，无需改配置文件或重建镜像。
|
|
|
+
|
|
|
+BREAKING CHANGE: DocumentRunConfig.llm.model 由必填改为可选，
|
|
|
+调用方传入的 model 不再参与兜底。
|
|
|
+
|
|
|
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
|
+```
|
|
|
+
|
|
|
+## 发版流程
|
|
|
+
|
|
|
+tag 采用 `vN.N.N` annotated tag，双远端推送（Gitee + Gogs）；`release`
|
|
|
+分支仅推 Gogs（触发外部 CI/CD）。详见 `docs/DEPLOYMENT.md`。
|
|
|
+
|
|
|
+若后续引入 conventional-changelog，本规范的 feat/fix/BREAKING CHANGE
|
|
|
+约束可直接支撑自动生成 Change log；当前未启用。
|
lkatzey