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] 用于性能补丁；

标签后面是被修改的模块名称。使用技术名称，因为功能名称可能会随时间变化。如果修改了多个模块，请列出它们，或者使用“various”表示这是跨模块的更改。除非确实需要或更容易实现，避免在同一个提交中修改多个模块的代码。理解模块历史可能会变得困难。

提交信息标题¶

在标签和模块名称之后是一个有意义的提交信息标题。它应该能够自我解释，并包括更改背后的原因。不要使用诸如“bugfix”或“improvements”之类的单个词。为了可读性，尝试将标题长度限制在大约 50 个字符以内。

提交信息标题在与 如果应用，此提交将<header> 连接后应形成一个完整的句子。例如， [IMP] base: prevent to archive users linked to active partners 是正确的，因为它形成了一个完整的句子 如果应用，此提交将阻止用户归档... 。

提交信息完整描述¶

在消息描述中，说明受您更改影响的代码部分（模块名称、库、横向对象等）以及更改的描述。

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

您所做的可以在提交本身中找到。如果涉及某些技术选择，最好在提交信息中解释原因之后也说明这些选择。顺便说一句，对于 Odoo 研发开发者来说，“产品团队让我这么做”并不是一个有效的“原因”。

请避免同时影响多个模块的提交。尝试将它们拆分为不同的提交，其中受影响的模块是不同的。如果我们需要单独回滚某个模块的更改，这将很有帮助。

不要犹豫，稍微详细一点。大多数人只会看到您的提交信息，并根据这几句话来评判您所做的一切。完全没有压力哦。

您花费了数小时、数天甚至数周时间开发有意义的功能。花点时间冷静下来，撰写清晰易懂的提交信息。

如果您是 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.

注解

使用长描述来解释“为什么”，而不是“是什么”，“是什么”可以在差异（diff）中看到。

Edit on GitHub