Odoo Git操作规范

配置您的 Git

根据前人经验与口口相传的惯例，以下做法能大大帮助您写出更有用的提交：

  • 请务必在本地 Git 配置中同时定义 user.email 和 user.name

    git config --global <var> <value>

  • 请务必在此处将您的全名添加到 GitHub 个人资料中。也请尽情发挥，添加您的团队、头像、您最喜欢的名言等等 ;-)

提交信息结构

提交信息包含四个部分：标签、模块、简短描述和完整描述。请尽量按推荐的结构撰写提交信息

[TAG] module: describe your change in a short sentence (ideally < 50 chars)

Long version of the change description, including the rationale for the change,
or a summary of the feature being introduced.

Please spend a lot more time describing WHY the change is being done rather
than WHAT is being changed. This is usually easy to grasp by actually reading
the diff. WHAT should be explained only if there are technical choices
or decision involved. In that case explain WHY this decision was taken.

End the message with references, such as task or bug numbers, PR numbers, and
OPW tickets, following the suggested format:
task-123 (related to task)
Fixes #123  (close related issue on Github)
Closes #123  (close related PR on Github)
opw-123 (related to ticket)

标签与模块名

标签用于为提交添加前缀，应为以下之一

  • [FIX] 用于缺陷修复：多用于稳定版本，如果修复的是开发版本中近期的缺陷也同样适用；

  • [REF] 用于重构：当某项功能被大幅改写时；

  • [ADD] 用于新增模块；

  • [REM] 用于移除资源：移除无用代码、移除视图、移除模块等；

  • [REV] 用于回退提交：如果某个提交引发问题或不被需要，可使用此标签进行回退；

  • [MOV] 用于移动文件：请使用 git move，且不要更改被移动文件的内容，否则 Git 可能丢失该文件的跟踪记录与历史；从一个文件向另一个文件移动代码时也使用此标签；

  • [REL] 用于发布提交：新的主要或次要稳定版本；

  • [IMP] 用于改进：开发版本中的大多数更改都是与其他标签无关的增量改进；

  • [MERGE] 用于合并提交：既用于缺陷修复的前向移植，也用作涉及多个独立提交的功能的主提交；

  • [CLA] 用于签署 Odoo 个人贡献者许可协议；

  • [I18N] 用于翻译文件的更改；

  • [PERF] 用于性能补丁；

  • [CLN] 用于代码清理；

  • [LINT] 用于 lint 检查；

标签之后是被修改的模块名。请使用技术名称，因为功能名称可能随时间变化。如果修改了多个模块，请逐一列出，或使用 various 表示这是跨模块的修改。除非确实必要或更为方便，否则请避免在同一个提交中修改多个模块的代码，否则理解模块历史会变得困难。

提交信息标题

在标签和模块名之后，是一个有意义的提交信息标题。标题应当不言自明，并说明更改的原因。不要只用一个词，如“bugfix”或“improvements”。为了便于阅读，请尽量将标题长度限制在约 50 个字符以内。

提交信息标题与 if applied, this commit will <header> 拼接后应构成一个通顺的句子。例如 [IMP] base: prevent to archive users linked to active partners 是正确的，因为它构成了通顺的句子 if applied, this commit will prevent users to archive...。

提交信息完整描述

在信息描述中，请说明您的更改所影响的代码部分（模块名、库、跨模块对象等）以及更改说明。

首先解释您为什么要修改代码。如果有人在约 40 年后（或 3 天后）回看您的提交，重要的是您当时为什么这样做，也就是更改的目的。

您做了什么可以从提交本身看出。如果涉及一些技术选择，最好在提交信息中于“为什么”之后一并说明。顺便说一句，对于 Odoo 研发开发者来说，“PO 团队让我这么做”并不是一个有效的“为什么”。

请避免同时影响多个模块的提交。请尽量按受影响的模块拆分成不同的提交。如果我们需要单独回退某个模块中的更改，这样做会很有帮助。

不要吝惜笔墨，多写一些无妨。大多数人只会看到您的提交信息，并仅凭这几句话来评判您一生所做的所有事情。完全不用有压力。

您花费数小时、数天或数周开发有意义的功能。请花些时间冷静下来，编写清晰易懂的提交信息。

如果您是 Odoo 研发开发者，那么“为什么”应当是您所处理任务的目的。完整的规格说明构成了提交信息的核心。如果您正在处理的任务缺乏目的和规格说明，请考虑在继续之前将其明确。

最后，以下是一些正确提交信息的示例：

[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.

注解

使用长描述来解释 为什么 而不是 做了什么，做了什么 可以从差异中看到