odoo-commit

工作流

1. 运行 git diff --stat 和 git status --short，查看有哪些变更；再运行 git log -1 --oneline（如果存在远程跟踪分支，则运行 git log @{u}.. --oneline），查看最近的本地提交以及它是否尚未推送。

2. 如果这项变更是对尚未推送的 HEAD 提交的直接延续或修复，请跳过撰写新消息，直接将变更合并进去，而不是为同一逻辑变更创建第二个提交：

   git add <file>
   git commit --amend --no-edit   # or drop --no-edit to also revise the message
   

   否则，撰写新的提交消息。

3. 按名称暂存相关文件，绝不使用 git add -A 或 git add .。

4. 将提交消息写入临时文件，然后使用 git commit -F 提交：

cat > /tmp/odoo-commit-message.txt <<'EOF'
[TAG] module: short description

Optional body line.
EOF
git commit -F /tmp/odoo-commit-message.txt

也可以使用任何等效的临时文件流程（例如使用 PowerShell 的 Set-Content 或其他编辑器），只要最终通过 git commit -F <file> 创建提交即可。

5. 创建拉取请求之前，将自己反复修改产生的提交压缩为每项逻辑变更对应的一个干净提交（参见 OCA 指南）： 其他人不需要看到你中间的“修复错误 1”“修复错误 2”历史——只需要最终状态和清晰的摘要。对于单个后续修复，通常只需使用 git commit --amend（步骤 2）；若要将多个提交合并为一个，请改用交互式变基：

   git rebase -i HEAD~N   # N = number of commits to fold
   

   将第一行保留为 pick，并使用真实的 [TAG] module: description 消息；将其余提交标记为 fixup（丢弃它们的消息）或 squash（合并消息）：

   pick 1949129 [IMP] module: Introduce feature A
   fixup d2cf643 Fix bug 1 of feature A
   fixup 42bd9e8 Fix bug 2 of feature A
   fixup 7f767d5 Fix bug 3 of feature A
   

   无论采用哪种方式，只重写仍在本地、尚未推送的提交，或你独自拥有的分支上的提交——未经用户确认，绝不修改或变基共享历史。

6. 报告生成的提交哈希和主题。

不要绕过 pre-commit 钩子。如果钩子失败，请修复问题、重新暂存变更，然后重新创建提交。

格式

[TAG] module: short description

Optional body explaining WHY, not what. What is visible in the diff.
Focus on motivation, constraints, and decisions made.

task-XXXX, opw-XXXXXX

主题行规则

• [TAG] module: description——方括号内为标签，后接模块名称、冒号、空格和描述
• 为便于阅读，整个标题（[TAG] module: description）应控制在约 50 个字符；72 个字符是硬性上限，不要以此为目标
• 自检：将标题放在“如果应用，此提交将 <header>”之后，应构成有效句子。例如 [IMP] base: prevent to archive users linked to active partners → “如果应用，此提交将阻止归档与活跃合作伙伴关联的用户”
• 描述不得使用“bugfix”或“improvements”等单一、含糊的词语；必须清楚说明变更原因
• 使用祈使语气：“add”“fix”“remove”，不要使用“added”“fixes”
• 末尾不加句号
• 模块 = 技术模块名称（例如 hhc、plc、nhso_stddataset、imc）
• 避免在一个提交中涉及多个模块——按模块拆分，以便分别还原。若确实无法避免，请列出涉及的模块或使用 various

标签

• [FIX]——错误修复；用于稳定版本，也适用于近期开发中发现的错误
• [REF]——重构：大幅改写功能
• [ADD]——添加新模块
• [REM]——移除资源：废弃代码、视图、模块
• [REV]——还原提交
• [MOV]——移动文件（不更改内容；使用 git mv）
• [REL]——发布提交：稳定版本的主要或次要版本
• [IMP]——改进：大多数渐进式开发变更
• [MERGE]——合并提交／向前移植错误修复
• [CLA]——签署 Odoo 个人贡献者许可协议
• [I18N]——翻译文件变更
• [PERF]——性能补丁
• [CLN]——代码清理
• [LINT]——代码检查

正文规则

• 如果主题本身已能清楚说明内容，则省略正文
• 以下情况应包含正文：不明显的原因、破坏性变更、迁移说明、任务引用
• 解释原因，而非变更内容——差异已经展示了变更内容。只有涉及技术选择或权衡时，才值得说明变更内容；此时应解释为何作出该选择
• 不要为了简短而刻意压缩：Odoo 官方指南明确指出，如果有充分理由，不必犹豫使用较长的说明。每一行仍应有其价值——不要复述差异，也不要填充内容
• 每行不超过 72 个字符
• 在末尾引用任务 ID：task-XXXX、opw-XXXXXX、Fixes #123、Closes #123

绝不可包含的内容

• “This commit does X”（此提交执行了 X）——差异已说明变更内容
• “I”（我）、“we”（我们）、“now”（现在）、“currently”（目前）
• 任何形式的 AI 署名：Co-Authored-By: Claude ... 页脚、Generated with Claude Code 行、会话链接。如果工具自动添加了这些内容，请在提交前移除
• 如果主题已经说明文件名或模块，就不要再重复

Pull Request

• 标题 = 提交标头（[TAG] module: description）；每个 PR 只包含一个逻辑变更
• 正文说明原因以及如何验证（测试命令、视图截图）；差异展示变更内容
• 正文中不得出现任何 AI 署名：不得包含 “Generated with” 页脚、Co-Authored-By、会话链接
• 不要添加或编辑作者／审阅者行；git 已记录作者

示例

以下示例摘自 Odoo 官方 git 指南：

[REF] models: use `parent_path` to implement parent_store

This replaces the former modified preorder tree traversal (MPTT) with the
fields `parent_left`/`parent_right`[...]

[FIX] account: remove frenglish

[...]

Closes #22793
Fixes #22769

[FIX] website: remove unused alert div, fixes look of input-group-btn

Bootstrap's CSS depends on the input-group-btn element being the first/last
child of its parent. This was not the case because of the invisible and
useless alert.

仅含标头的示例，用于说明“完整句子”自检：

[IMP] base: prevent to archive users linked to active partners