odoo-commit-message-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Odoo Commit Message Guidelines

Odoo提交消息规范

Purpose

目的

Use this skill to produce high-quality Odoo commit messages that are consistent, reviewable, and easy to revert.

使用本技能生成一致、便于评审且易于回滚的高质量Odoo提交消息。

Local References

本地参考资料

This skill includes reference material in:

```
references/git_guidelines.md
```
(official Odoo commit message conventions)
```
references/CONTRIBUTING.md
```
(OCA contribution and commit message extensions)

Use these files as source context when user requests stricter validation, edge-case tagging decisions, or policy justification.

本技能包含以下参考资料：

```
references/git_guidelines.md
```
（官方Odoo提交消息约定）
```
references/CONTRIBUTING.md
```
（OCA贡献及提交消息扩展规范）

当用户要求更严格的验证、边缘场景下的标签选择决策或政策依据时，可以将这些文件作为参考上下文。

When To Use

使用场景

Use this skill when the user asks to:

write a new commit message for Odoo code
rewrite or improve an existing commit message
validate whether a commit message follows Odoo rules
choose the correct Odoo tag

当用户提出以下需求时，使用本技能：

为Odoo代码编写新的提交消息
重写或优化现有提交消息
验证提交消息是否符合Odoo规则
选择正确的Odoo标签

Required Inputs

必要输入

Before drafting, collect:

modified module name (or
```
various
```
for cross-module commits)
change type and intent (bug fix, refactor, migration, etc.)
core rationale (WHY the change is needed)
notable implementation choices (only if relevant)
references (
```
task-*
```
,
```
ticket-*
```
,
```
Fixes #
```
,
```
Closes #
```
,
```
opw-*
```
) when available
specific CI directives (e.g.,
```
[NO CI]
```
) if mentioned by the user

If required inputs are missing, ask only the minimum concise follow-up questions.

起草提交消息前，需要收集以下信息：

被修改的模块名称（跨模块提交时使用
```
various
```
）
变更类型与意图（bug修复、重构、迁移等）
核心原因（为什么需要此变更）
值得注意的实现选择（仅在相关时提供）
参考信息（如
```
task-*
```
、
```
ticket-*
```
、
```
Fixes #
```
、
```
Closes #
```
、
```
opw-*
```
，如有提供）
特定CI指令（例如
```
[NO CI]
```
，如果用户提及）

如果缺少必要输入，仅询问最关键的补充问题。

Output Format

输出格式

Use this structure:

text

[TAG] module: short summary (ideally < 50 chars)

WHY the change is needed.
WHAT changed and technical choices (only if useful).

task-123
ticket-12345
Fixes #123
Closes #456
opw-789

Rules:

Commit message must be in English.
Header must start with a tag from
```
Tag Selection Rules
```
in this exact pattern:
```
[TAG]
```
(e.g.,
```
[FIX]
```
,
```
[ADD]
```
).
The tag must be uppercase and enclosed in brackets; reject lowercase or malformed tags.
Keep header concise; target about 50 characters in the summary part.
Body must be multiline and wrapped to 72 characters per line.
Body should use structured plain text (lists using
```
*
```
or
```
-
```
). Avoid advanced Markdown (like tables) since commit messages are read in terminals.
Use imperative present voice:
```
Fix
```
,
```
Remove
```
,
```
Add
```
(not
```
Fixes
```
,
```
Removes
```
).
Make the header meaningful; avoid generic summaries like
```
bugfix
```
.
Prioritize WHY over WHAT in the body.

Compatibility note:

Official Odoo documentation does not define
```
[MIG]
```
as a core tag.
```
[MIG]
```
is the official standard for Odoo Community Association (OCA) repositories. If the repository workflow uses migration tags,
```
[MIG]
```
can be used.

使用以下结构：

text

[TAG] module: short summary (ideally < 50 chars)

WHY the change is needed.
WHAT changed and technical choices (only if useful).

task-123
ticket-12345
Fixes #123
Closes #456
opw-789

规则：

提交消息必须使用英文。
标题必须以
```
标签选择规则
```
中的标签开头，格式严格为
```
[TAG]
```
（例如
```
[FIX]
```
、
```
[ADD]
```
）。
标签必须为大写且用方括号包裹；拒绝小写或格式错误的标签。
标题需简洁；摘要部分目标约50个字符。
正文必须为多行，每行最多72个字符。
正文应使用结构化纯文本（使用
```
*
```
或
```
-
```
的列表）。避免使用复杂Markdown（如表），因为提交消息会在终端中查看。
使用命令式现在时态：
```
Fix
```
、
```
Remove
```
、
```
Add
```
（而非
```
Fixes
```
、
```
Removes
```
）。
标题需有实际意义；避免
```
bugfix
```
这类通用摘要。
正文中优先说明原因（WHY）而非内容（WHAT）。

兼容性说明：

官方Odoo文档未将
```
[MIG]
```
定义为核心标签。
```
[MIG]
```
是Odoo社区协会（OCA）仓库的官方标准。如果仓库工作流支持迁移标签，则可以使用
```
[MIG]
```
。

Tag Selection Rules

标签选择规则

Choose exactly one main tag for the commit:

```
[FIX]
```
bug fix
```
[REF]
```
major refactor / heavy rewrite
```
[ADD]
```
add a new module
```
[REM]
```
remove dead code/resources/modules
```
[REV]
```
revert an earlier commit
```
[MOV]
```
move files/code while preserving history intent
```
[REL]
```
release commit
```
[IMP]
```
incremental improvement
```
[MERGE]
```
merge / forward-port integration commit
```
[CLA]
```
individual contributor license signature
```
[I18N]
```
translation updates
```
[PERF]
```
performance improvement
```
[CLN]
```
cleanup
```
[LINT]
```
linting pass
```
[MIG]
```
module migration (only when the project convention supports it)

Decision guidance:

Prefer the tag that best captures intent, not file type.
If it is clearly a migration, use
```
[MIG]
```
.
If it fixes a regression while migrating, split into two commits when possible.
Avoid stacking multiple tags in one header.

为提交选择恰好一个主标签：

```
[FIX]
```
修复bug
```
[REF]
```
重大重构/深度重写
```
[ADD]
```
添加新模块
```
[REM]
```
删除无用代码/资源/模块
```
[REV]
```
回滚早期提交
```
[MOV]
```
移动文件/代码同时保留历史意图
```
[REL]
```
版本发布提交
```
[IMP]
```
增量改进
```
[MERGE]
```
合并/向前移植集成提交
```
[CLA]
```
个人贡献者许可签名
```
[I18N]
```
翻译更新
```
[PERF]
```
性能优化
```
[CLN]
```
清理
```
[LINT]
```
代码检查
```
[MIG]
```
模块迁移（仅当项目约定支持时使用）

决策指导：

优先选择最能体现意图的标签，而非根据文件类型选择。
如果明确是迁移操作，使用
```
[MIG]
```
。
如果在迁移过程中修复了回归问题，尽可能拆分为两个提交。
避免在一个标题中使用多个标签。

Module Naming Rules

模块命名规则

Use technical module name, not marketing/functional display names.
If multiple modules are touched, list them briefly or use
```
various
```
.
Prefer one logical change per commit and avoid large cross-module commits.

使用技术模块名称，而非营销/功能显示名称。
如果涉及多个模块，简要列出或使用
```
various
```
。
优先每个提交对应一个逻辑变更集，避免大型跨模块提交。

Writing Workflow

编写流程

Identify the smallest logical change set.
Choose the module scope.
Select the tag from the rule set above.
Draft header:
```
[TAG] module: imperative summary
```
.
Draft body with WHY first, then concise WHAT if needed (plain text, wrapped at 72 chars).
Add references and CI directives at the end using canonical formats.
Validate against checklist before returning.

确定最小的逻辑变更集。
选择模块范围。
从上述规则中选择标签。
起草标题：
```
[TAG] module: 命令式摘要
```
。
起草正文，先说明原因，再简要说明内容（如果有用）（纯文本，每行最多72字符）。
添加符合规范的参考信息和CI指令。
返回前根据检查清单验证。

Validation Checklist

验证检查清单

Confirm all items:

Header follows
```
[TAG] module: summary
```
.
Header starts with exactly one valid tag from
```
Tag Selection Rules
```
.
Tag token is uppercase and bracketed (
```
[FIX]
```
, not
```
[fix]
```
or
```
FIX
```
).
Summary is concise and not truncated with ellipsis in PR UI.
Body lines are wrapped at max 72 characters.
Body formatting avoids advanced Markdown, using simple plain text.
Rationale (WHY) is explicit.
Verb tense is imperative present.
Tag matches change intent.
Module naming is technical and accurate.
Commit scope is a single logical change set.
References are formatted correctly when present.

If any check fails, rewrite the message before returning.

确认所有项：

标题遵循
```
[TAG] module: summary
```
格式。
标题以
```
标签选择规则
```
中的恰好一个有效标签开头。
标签为大写且用方括号包裹（如
```
[FIX]
```
，而非
```
[fix]
```
或
```
FIX
```
）。
摘要简洁，不会在PR界面中被截断。
正文每行最多72个字符。
正文格式避免复杂Markdown，使用简单纯文本。
明确说明原因（WHY）。
动词时态为命令式现在时。
标签与变更意图匹配。
模块名称技术准确。
提交范围为单个逻辑变更集。
参考信息格式正确（如果存在）。

如果任何检查项不通过，返回前重写消息。

Good Examples

优秀示例

text

[FIX] website: remove unused alert div

Fix the look of input-group-btn.
Bootstrap requires input-group-btn to be the first or last child.
An invisible alert node broke that structure and produced visual issues.

Fixes #22769
Closes #22793

text

[FIX] various: resolve rounding issues in currency conversions

Address inconsistent decimal rounding behavior across multiple reporting
and accounting modules. Instead of allowing components to do ad-hoc
rounding, enforce standard decimal precision in the core tools.

ticket-10928
[NO CI]

text

[IMP] web: add module system to web client

Introduce a module system for JavaScript code to improve isolation,
load order control, and maintainability as the client grows.

text

[MIG] stock_account: migrate valuation hooks to 19.0

Align valuation hook signatures with 19.0 API to preserve extension
compatibility and avoid runtime errors during upgrade.

task-8421

text

[FIX] website: remove unused alert div

Fix the look of input-group-btn.
Bootstrap requires input-group-btn to be the first or last child.
An invisible alert node broke that structure and produced visual issues.

Fixes #22769
Closes #22793

text

[FIX] various: resolve rounding issues in currency conversions

Address inconsistent decimal rounding behavior across multiple reporting
and accounting modules. Instead of allowing components to do ad-hoc
rounding, enforce standard decimal precision in the core tools.

ticket-10928
[NO CI]

text

[IMP] web: add module system to web client

Introduce a module system for JavaScript code to improve isolation,
load order control, and maintainability as the client grows.

text

[MIG] stock_account: migrate valuation hooks to 19.0

Align valuation hook signatures with 19.0 API to preserve extension
compatibility and avoid runtime errors during upgrade.

task-8421

Anti-Patterns To Reject

需要拒绝的反模式

Reject and rewrite messages with:

generic headers (
```
bugfix
```
,
```
improvements
```
)
missing module name
missing rationale
past tense or third-person verbs in header
oversized multi-topic commits in one message
truncated first line (
```
...
```
) caused by long header

拒绝并重写以下类型的消息：

通用标题（如
```
bugfix
```
、
```
improvements
```
）
缺少模块名称
缺少原因说明
标题使用过去式或第三人称动词
单个消息包含多个主题的大型提交
标题过长导致第一行被截断（
```
...
```
）

Response Behavior

响应行为

When asked to produce a commit message:

Return only the raw commit message (no code fences) unless the user asks for explanation.
If info is missing, ask only the minimum necessary clarifying questions.
If user provides a draft, return a corrected Odoo-compliant version.
Be strict: if the header does not begin with one uppercase bracketed tag from
```
Tag Selection Rules
```
, rewrite it before returning.
For IDE Source Control usage, return a ready-to-use commit message suggestion that can be inserted directly in the Source Control commit box (no preamble, no labels, no markdown).
Execution Offer: After providing the generated commit message, proactively offer to execute the commit using
```
git commit -m "..." -m "..."
```
. Always ask for explicit user confirmation before running the
```
git commit
```
command. Do not execute the commit automatically.

当被要求生成提交消息时：

仅返回原始提交消息（不使用代码块），除非用户要求解释。
如果信息缺失，仅询问必要的澄清问题。
如果用户提供了草稿，返回符合Odoo规范的修正版本。
严格执行：如果标题未以
```
标签选择规则
```
中的大写方括号标签开头，返回前重写。
对于IDE源代码控制使用场景，返回可直接插入源代码控制提交框的提交消息建议（无前言、无标签、无Markdown）。
执行提议：提供生成的提交消息后，主动提议使用
```
git commit -m "..." -m "..."
```
执行提交。在运行
```
git commit
```
命令前必须获得用户明确确认，不得自动执行。

Usage Examples

使用示例

Scenario 1: Create a new commit message

场景1：创建新的提交消息

User: "Write an Odoo commit message for a bug fix in

sale_stock

where delivered qty was computed twice. Reference task-9123."

Agent behavior:

Identify tag as
```
[FIX]
```
and module as
```
sale_stock
```
.
Draft concise header in imperative form.
Explain WHY first in body, then concise WHAT.
Append
```
task-9123
```
as reference.
Suggest the commit message and ask: "Would you like me to execute this commit for you?"

用户： "为

sale_stock

模块中已交付数量被计算两次的bug修复编写Odoo提交消息，参考task-9123。"

Agent行为：

确定标签为
```
[FIX]
```
，模块为
```
sale_stock
```
。
起草简洁的命令式标题。
正文中先说明原因，再简要说明内容。
附加
```
task-9123
```
作为参考。
提交消息，并询问："是否需要我帮您执行此次提交？"

Scenario 2: Rewrite an existing draft

场景2：重写现有草稿

User: "Improve this commit message:

fixed stuff in stock module

Agent behavior:

Reject generic summary and missing rationale.
Ask minimum questions if context is missing (what bug, why needed).
Return corrected message in Odoo format.
Offer to execute the commit if the user is satisfied.

用户： "优化这个提交消息：

fixed stuff in stock module

Agent行为：

拒绝通用摘要和缺少原因的内容。
如果上下文缺失，仅询问必要的问题（如修复了什么bug，为什么需要修复）。
返回符合Odoo格式的修正消息。
如果用户满意，提议执行提交。

Scenario 3: Validate tag choice

场景3：验证标签选择

User: "I changed API hooks for 19.0 migration and also fixed a small bug. Should I use

[MIG]

[FIX]

Agent behavior:

Prefer
```
[MIG]
```
for migration intent.
Recommend splitting migration and bug fix into separate commits when possible.
Provide one valid commit message for each resulting commit if requested.
Offer to stage and execute both commits sequentially.

用户： "我为19.0版本迁移修改了API钩子，还修复了一个小bug。我应该使用

[MIG]

还是

[FIX]

？"

Agent行为：

优先为迁移意图使用
```
[MIG]
```
。
建议尽可能将迁移和bug修复拆分为两个独立提交。
如果用户要求，为每个提交提供一个有效的提交消息。
提议依次暂存并执行两个提交。