闲言

写出好的 commit message

转自:http://ruby-china.org/topics/15737

 

为什么要关注提交信息

  • 加快 Reviewing Code 的过程
  • 帮助我们写好 release note
  • 5年后帮你快速想起某个分支，tag或者commit增加了什么功能，改变了哪些代码
  • 让其他开发者在运行 git blame的时候想跪谢
  • 总之一个好的提交信息，会帮助你提高项目的整体质量

基本要求

  • 第一行应该少于50个字。随后是一个空行 第一行题目也可以写成：Fix issue #8976

  • 喜欢Vim的哥们把下面这行代码加入.vimrc文件中，来检查拼写和自动折行

    autocmd Filetype gitcommit setlocal spell textwidth=72`

  • 永远不在git commit 上增加 -m <msg>或者 --message=<msg>参数，而单独提交信息。
    一个不好的例子 git commit -m "Fix login bug"
    一个推荐的commit message应该是这样的：

    `Redirect user to the requested page after login

https://trello.com/path/to/relevant/card

Users were being redirected to the home page after login, which is less
useful than redirecting to the page they had originally requested before
being redirected to the login form.

    * Store requested path in a session variable
    * Redirect to the stored location after successfully logging in the user`
  • 注释最好包含一个链接指向项目的issue/story/card。一个完整的链接比一个issue number更好

  • 提交信息中包含一个简短的故事，让别人更容易理解你的项目

    注释要回答以下问题

    为什么这次修改是必要的？
    要告诉Reviewers，你的提交包含什么改变。让他们更容易审核代码和忽略无关的改变。

    如何解决的问题？
    这可不是说技术细节。看下面的两个例子：

    Introduce a red/black tree to increase search speed 
  Remove <troublesome gem X>, which was causing <specific description of issue introduced by gem>

    如果你的修改特别明显，就可以忽略这个。

    这些变化可能影响那些地方？
    这是你最需要回答的问题。因为他会帮助你发现在某个branch或者commit中做了过多的改动。一个提交尽量只做1，2个变化。
    你的团队应该有一个自己的行为规范，规定每个commit和branch最多能含有多少个功能修改。

    小提示

  • 使用fix，add，change而不是fixed，added，changed

  • 永远不要忘了第二行是空行

  • 应Line break来分割提交信息，让它在某些软件里面更容易读

    例子

    `Fix bug where user can't signup.

[Bug #2873942]

Users were unable to register if they hadn't visited the plans
and pricing page because we expected that tracking
information to exist for the logs we create after a user
signs up.  I fixed this by adding a check to the logger
to ensure that if that information was not available
we weren't trying to write it.`

    `Redirect user to the requested page after login

    https://trello.com/path/to/relevant/card

    Users were being redirected to the home page after login, which is less
    useful than redirecting to the page they had originally requested before
    being redirected to the login form.

    • Store requested path in a session variable
    • Redirect to the stored location after successfully logging in the user

参考文献