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)

标签和模块名称

标签用于在您的提交前添加前缀。它们应为以下之一

  • [修复]:用于错误修复:主要在稳定版本中使用,但如果在开发版本中修复了一个近期出现的错误,同样适用;

  • [参考] 用于重构:当一个功能被大幅重写时;

  • [添加],用于添加新模块;

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

  • [REV] 用于回退提交:如果某个提交导致问题或不希望保留,可以通过此标签进行回退;

  • [移动] 用于移动文件:使用 git move 命令,不要修改被移动文件的内容,否则 Git 可能会丢失该文件的跟踪和历史记录;也用于将代码从一个文件移动到另一个文件时。

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

  • [改进]:对于改进:开发版本中的大多数更改都是增量改进,与另一个标签无关;

  • [合并]:用于合并提交:在向前移植错误修复时使用,也作为涉及多个独立提交的功能的主要提交;

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

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

  • [性能] 用于性能补丁;

标签之后是修改后的模块名称。请使用技术名称,因为功能名称可能会随时间而变化。如果多个模块被修改,请列出它们,或使用“各种”来表明这是跨模块的修改。除非确实需要或更方便,否则避免在同一个提交中修改多个模块的代码。这可能会使理解模块历史变得困难。

提交信息标题

在标签和模块名称之后,是具有意义的提交消息标题。该标题应自成一体,包含更改的原因。不要使用像 “bugfix” 或 “improvements” 这样的单个词语。尽量将标题长度控制在约 50 个字符以内,以提高可读性。

Commit message header should make a valid sentence once concatenated with if applied, this commit will <header>. For example [IMP] base: prevent to archive users linked to active partners is correct as it makes a valid sentence if applied, this commit will prevent users to archive....

提交信息完整描述

在消息描述中指定您的更改所影响的代码部分(模块名称、库、通用对象等)以及更改的描述。

首先解释你为什么要修改代码。如果有人在大约40年后(或3天后)回顾你的提交,重要的是要说明你这样做的原因。这就是更改的目的。

你所做的内容可以在提交信息中找到。如果涉及了一些技术选择,建议在提交信息中也解释一下原因。对于 Odoo 研发团队的开发者来说,”PO 团队让我这么做” 并不是一个有效的理由。

请避免同时影响多个模块的提交。如果受影响的模块不同,请尝试拆分为不同的提交。这样在需要单独回滚某个模块的更改时会更加方便。

不要犹豫,适当详细一些。大多数人只会看到你的提交信息,并仅凭这几句话就对你一生所做的事做出判断。完全没有压力。

你在有意义的功能上花费了数小时、数天或数周的时间。请花点时间冷静下来,编写清晰易懂的提交信息。

如果你是 Odoo R&D 开发人员,那么 WHY 应该是你所从事任务的目的。完整的规格说明是提交信息的核心。如果你正在处理一个缺乏目的和规格的任务,请在继续之前先明确这些内容。

最后,这里是一些正确提交信息的示例:

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

注解

请使用长描述来解释*为什么*,而不是*是什么*,*是什么*可以在差异中看到