如何编写一条好的提交消息¶
快速参考¶
良好提交的示例:
我们正在查看拉取请求 #5759
Haskell.py: Add Haskell.py file
Add a new python file in
coalib/bearlib/languages/definitions/Haskell.py
Closes https://github.com/coala/coala/issues/5330
- Haskell.py: Add Haskell.py file :描述中的更改
最多50个字符。
- Add a new python file in.. ..Haskell.py :描述推理
每行最多72个字符的更改。
- Closes https://github.com/coala/coala/issues/5330 :提及URL
它关闭或修复的问题。
我们现在正在查看拉取请求 #5789
ConfParserTest.py: Fix typos in comments
This fixes multiple occurences of typos in the comments
omment --> comment
inexistent --> non-existent
Closes https://github.com/coala/coala/issues/5785
- ConfParserTest.py: Fix typos in comments :描述中的更改
最多50个字符。
为了清楚起见,请注意此示例的简短日志显示为“Fix”。然而,这并不是一个实际的bug修复,它既没有解决bug,也没有在GitHub上标记为bug,就像“示例3(修复了拼写错误)”中的Pull请求一样,您可以在下面看到。也就是说,在这种情况下使用术语“修复”是可以接受的。
- This fixes.. ..non-existent :描述一下你做出改变的理由
每行最多72个字符。
- Closes https://github.com/coala/coala/issues/5785 :提及URL
它关闭或修复的问题。
在Coala,我们非常关注代码的可维护性。
备注
代码更多的是读而不是写!
我们需要好的代码,为了实现它,我们要确保代码的每一次更改(即提交)都会让它变得更好。
怎样才是一个好的承诺¶
好的承诺是原子的。它应该描述一个变化,而不是更多。
为什么?因为如果每次提交有更多的更改,我们可能会产生更多的错误。
如何编写良好的提交消息¶
提交消息由3部分组成:
短日志
提交正文
出库参照
例子:
Haskell.py: Add Haskell.py file
Add a new python file in coalib/bearlib/languages/definitions/Haskell.py
Closes https://github.com/coala/coala/issues/5330
短日志¶
例子:
Haskell.py: Add Haskell.py file
- 最多50个字符。将主题行保持在此长度可确保它们的可读性,并以简明的方式解释更改。
应该描述一下 改变 -提交中正在执行的操作。
不应包含WIP前缀。
应该有一个标记和一个用冒号分隔的简短描述 (
:
)Tag
正在修改的文件、类或包。
不是强制性的。
简短描述
以大写字母开头。
用祈使现在时书写(即
Add something
不是Adding something
或Added something
)没有拖尾期。
提交正文¶
例子:
Add a new python file in coalib/bearlib/languages/definitions/Haskell.py
- 最多72个字符,不包括换行符 each 行。建议添加72个字符的换行符,这样Git就有足够的空间缩进文本,同时将所有内容保持在80个字符以内。
不是强制性的-但有助于解释您在做什么。
应该描述您更改的理由。这对于不是不言而喻的复杂更改尤其重要。这也是写相关bug的正确位置。
这里不应该用第一人称。
出库参照¶
例子:
Closes https://github.com/coala/coala/issues/5330
应使用
Fixes
关键字(如果提交修复了错误),或者Closes
如果它添加了功能/增强功能。在某些情况下,例如文档中克服的错误,
Fixes
和Closes
可能是非常小的和主观的。如果某个特定问题可能导致用户或程序的意外行为,则应将其视为错误,并应通过Fixes
。如果问题的标签为type/bug
您应该始终使用Fixes
。对于所有其他问题,请使用Closes
.如果您的提交没有结束某个问题,但它与该问题相关,并且部分解决了该问题,请使用
Related to
而不是Fixes
或Closes
.应使用问题的完整URL。
之间应该有一个空格
Fixes
,Closes
或Related to
和URL。
备注
问题引用将自动在问题中添加提交链接。
当提交被接受到Coala中时,它还将自动关闭该问题。
更多示例¶
示例1(修复错误并添加增强功能):拉取请求 #4217
Diff.py: Remove has_changes and fix __bool__
Removes the self.has_changes property, since its functionality can be
accessed from the bool conversion.
Fixes inconstency of __bool__ that results from looking at
self._changes:
removing one line, then adding the same content again resulted in
bool(diff) == True, instead of False.
__bool__ now uses the mechanism that was employed by has_changes, to
fix this bug.
Closes https://github.com/coala/coala/issues/4178
示例2(实施的功能):拉取请求 #435
Update the CI1, CI2 , & CI3 tasks to refer to 2017
This commit changes all occurrences of 2016 to 2017 and the project
links with the new ones in use_coala.md, use_coala_2.md and
use_coala_3.md.
Closes https://github.com/coala/projects/issues/433
示例3(修复打字错误):拉取请求 #5544
Language: Change `TrumpScript` aliases
This changes aliases of TrumpScript in the
doctests so that TypeScript and TrumpScript
have different aliases and so do not collide.
Fixes https://github.com/coala/coala/issues/5541
示例4(相关):拉取请求 #5624
.moban.yaml: Add cached_property
This was omitted from 54622c2.
Related to https://github.com/coala/coala/pull/5618
编辑提交消息¶
如果您以前进行了提交,并在以后更新它,则建议您也相应地更新提交消息。
要做到这一点,可以使用如上所述的修改功能 here.
为什么我们需要好的承诺?¶
原子提交更容易检查。因此,由于更改的复杂性较低,审查者将能够更快地审查并发现更多的错误。
原子提交就像面向对象编程中的好对象--您可以将一个较大的对象拆分成许多小对象。降低复杂性是开发好的软件并在缺陷出现之前发现其缺陷的关键。
好的提交消息使您可以轻松地一目了然地检查某一时间范围内发生的情况。
在没有副作用的情况下恢复单个更改要容易得多。一次恢复多个提交很容易,但恢复一部分提交就不容易了。
git blame
会更有效。这是您能得到的最好的文档。代码越旧,它拥有的文档就越多。提交消息越好,隐藏的文档就越好。您的提交消息记录了您对任何行所做的每一次更改的原因。git bisect
会更有效。如果您将原子提交一分为二,以找到导致错误的提交,您应该能够快速识别错误的真正原因。良好的提交消息和提交的原子性是这种能力的关键。