有哪些比较好的 git commit message 书写规范?

据我了解,目前使用比较多的是 angular 规范,相关介绍文章:

它的 commit message 格式为:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

概括起来就是 header, body, fotter 三部分。其中 body 和 footer 可选。

header 只有一行,它又分为三部分:

  • type: 提交类型,有如下定义
    • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
    • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
    • docs: Documentation only changes
    • feat: A new feature
    • fix: A bug fix
    • perf: A code change that improves performance
    • refactor: A code change that neither fixes a bug nor adds a feature
    • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
    • test: Adding missing tests or correcting existing tests
  • scope: 影响范围,可选。
  • subject: 简短描述,以动词开头,长度不超过 50

总体看起来不错,但有时又觉得别扭,例如当提交 fix 类型的时候,就不好用 Fix 来描述修改了:fix: Fix

另外还规定必须在 footer 关闭 issue,所以 angular 仓库就能看到大量类似这样冗余的写法:

docs: the token should be associated with LibHeaderComponent (#40922)

PR Close #40922

一个 issue 号写了两遍。


其他书写规范:

1

https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/Appendix/CommitMessage.html

Some examples of topic descriptions

[BUGFIX] Throw HttpStatusExceptions in BackendController

[FEATURE] Add option to hide BE search box in list mod

[!!!][FEATURE] Implement new BE login form service

[!!!][TASK] Replace Foo API with new approach

[SECURITY] Escape record title in RecordsOverview

Note: The [!!!] prefix is added at the very beginning of the line, so it doesn’t get overlooked.

这个也必须在 footer 里边关闭 issue。

2

Here’s my commit message template:

## If applied, this commit will...
## [Add/Fix/Remove/Update/Refactor/Document] [issue #id] [summary]


## Why is it necessary? (Bug fix, feature, improvements?)
-
## How does the change address the issue?
-
## What side effects does this change have?
-

… and it comes out looking something like this:

Fix #16 missing CSS variables
- Fix for unstyled elements
- Add background color, height for code blocks
- Only affects highlight class

这个似乎不错,Fix 即表示类型又当动词用(不用想别的替代动词),一行就可以关闭 issue。而且不用冒号/括号,看起来比较自然。

3

I use

[Abc]: Message.

With Add, Mod(ify), Ref(actoring), Fix, Rem(ove) and Rea(dability) then it’s easy to extract logfile.

Example :

Add: New function to rule the world.  
Mod: Add women factor in Domination.ruleTheWorld().  
Ref: Extract empathy stuff to an abstract class.  
Fix: RUL-42 or #42 Starvation need to be initialised before Energy to avoid the nullpointer in People.  
Rem: freeSpeech is not used anymore.  
Rea: Removed old TODO and extra space in header.  

这个也挺简洁。

4

We use the following:

[Ticket's Id in JIRA]: [Message: What was done] For example - ABC-123: Added ability to configure presentation per region.

In this case with proper integration you will be able to get changed/deleted/added files in your issue tracker. However, be aware that you should prevent something like ABC-123: Done or ABC-123: Fixed with filters if possible.

这个略为死板,提交 feature 之前必须先开 ticket。

这个答案下边有人给出了类似的规范:

[ticketId][ABC][topicId][WIP] Message, where:

ticketId - id of an item in task repository
ABC - add (feature), fix (bugfix), str (structure), dep (dependency) rem (backward incompatibility/remove), rea (readability), ref (refactoring)
topicId - can be a job selector for jenkins and/or branch name and/or topic name for gerrit
WIP - work in progress/or not (i.e. Continuous Integration may requires this)
message - detail of the modification

Examples:

[#452567][add][menu_item] new item - guestbook
[#452363][fix][banner_top][WIP] 1024x300 can be used now
[#452363][fix][banner_top] 500x200 can be used now
[#452713][rem][page] left middle ad
6 个赞

强推 gitmoji

5 个赞

这个挺好

https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs

2 个赞

个人对feat这种缩写实在无感……

自己个人一直没法施行各种规范原因感觉在于有限的几个词没法概括操作,绝大多数时候就想简单的在 header 中说明修改,就我经常 Update filename to blabala,前面多的 update 感觉没啥用

GNU Emacs的commit message规范(参阅 https://github.com/emacs-mirror/emacs/blob/master/CONTRIBUTE#L157

简单来说,就是


<SYNOPSIS>

<DESCRIPTION>

<ACTIONS>

<FOOTER>
  • SYNOPSIS:对你的修改的一行简单描述。
Adding support for elephant.

如果你的提交比较无关紧要(没有必要生成进 Changelog 文件里),在Emacs仓库里,也可 以使用;前缀来标记这个commit message(但这做法没被GNU Coding Standard记载)

; Fix CI for elephant.
  • DESCRIPTION:可选,对提交更详细的描述。

  • ACTIONS:具体描述了提交里做了什么。由复数个下列定义组成

* <FILE>(<LOCATION>): <ACTION>

举例子

* lisp/animal.el(elephant): New class.
* lisp/animal-actions(animal-walk): Implment generic function for elephant. 

* docs/memes.texi(How to put an elephant into the fridge): New section.
  • FOOTER:一些额外信息,通常按邮件头格式,如
Sign-off-by: Zhu Zihao <[email protected]>
Copyright-assignment-exemption: yes 
4 个赞

Conventional Commits 规范 这种引入了所谓“类型”的概念,鼓励用户尽量一个commit做一件事情,但是在开源活动里往往不太奏效

1个commit做一件事,这样一个非trivial的提交,往往会被拆成几个commit,合并时为了保证规范也不能squash & merge。当几十上百个人同时在一个项目里合作,最终git log的结果就像一团乱麻。

有人会说可以把一个大project拆分成好几个PR,每个PR单独squash & merge 。我的感觉是这样做会导致效率严重下降,更别说部分开源项目为了保证质量,采用 approval 机制,需要member几个点赞才能合并,分成几个PR更提高了贡献者找member点赞的成本。在一件连续的事里多次掺杂这样内耗的做法,极大的消耗维护者的精力,打击贡献者的热情。

我认为在提交里加入github issue号是不太好的行为,git本身是可靠的分布式系统,github issue不是。如果github issues哪天炸了数据丢失(Gitlab就炸过一次,不过它现在已经支持导出issue数据了)这些留在commit里的issue号就成了死链接。

1 个赞

提交里加 BUG 号(例如 Emacs)和 Ticket 号不也同样存在丢失的风险?本质上是一样的东西,它们都不存储在 git 仓库里。

Emacs的bug tracker是基于邮件列表的,谁想下载想备份可以随时进行,Github issues只能依赖官方

其实关键不在于格式,而在于提交的原子性,实际开发中很多开发者都无法保证自己的提交原子性,所以无法描述,造成很多提交消息都是类似 “改BUG” “添加测试” “什么和什么与什么”