Git commit message 撰寫和改進實例: mini-arm-os

tags: git, commit

如何寫一個 Git Commit Message - Louie譯

• 重新建立一段程式碼的脈絡是非常浪費的事情。我們無法避免這件事情的複雜性，因此我們應將心力放在儘可能的降低複雜度。Commit messages 正可以做到這點，而我們可以從 commit message 看出一個開發者是不是一位好的合作對象。

• 一個精心撰寫的 log 是漂亮以及有用的。git blame、revert、rebase、log、shortlog 以及其他相關的指令會進入到你的生活中。

• 一個 diff 可以告訴你什麼改變了，但是只有 commit message 可以正確的告訴你為什麼

• 文中提到為什麼我們會不注意 git commit 原因總歸沒有花很多時間使用 git log 以及相關的指令

• 團隊之間撰寫 commit log 的方式應該要相同。為了建立一個有用的修訂紀錄，團隊應該要先統一其 commit message 的風格，並且至少定義以下三件事情：

  • 風格. Markup syntax，wrap margins，文法，大寫慣例，符號慣例。定義這些事情，不要用猜的，並且讓它愈簡單愈好。最後的結果會得到一個非常一致的 log，不僅讓人們可以閱讀體會閱讀的樂趣，還能讓人定期的去閱讀它們。
  • 內容. 什麼樣的資訊需要放置在 commit message body 中？什麼不需要？
  • Metadata. issue tracking IDs, pull request 號碼等等的資料該如何被參照？

重要的七大規則

• 用一行空白行分隔標題與內容
• 限制標題最多只有 50 字元
• 標題開頭要大寫
• 標題不以句點結尾
• 以祈使句撰寫標題
• 內文每行最多 72 字
• 用內文解釋 what 以及 why vs. how

用一行空白行分隔標題與內容

$ git log --oneline -5 <branch>

我的版本

a998d57 Omit unnecessary mode switch The same problem on commit c7f9356. The implementation of context switch in "06-Preemptive" is different from previous version. It separates condition of `create_task()` into different block, so we can omit annoying checking that would trigger exception return or not and manipulate saving register on PSP directly.
b7751bc Fix unexpected exception return behavior This problem is the similar with commit c7f9356. Change the operation of `activate()` to omit unnecessary state switched.
c1e3bae Merge pull request #16 from yenWu/master
afb79b9 Fix unexpected intial content in user thread stack After creation of first user-level thread, the next thread is likely triggered by exception return. However, unexpected behavior occurs while the load of xPSR due to incorrect configuration on enabling carry flags in APSR at the initial stage.
684c4b7 update author list: Yen-Kuan Wu

這就是沒有空行的壞處Yen-Kwan Wu

Jserv 修改過的版本

b4c7473 Eliminate unnecessary mode switching
42e8415 Eliminate unnecessary state switching
3543bb9 Fix unexpected intial content in user thread stack
228f93c update author list: Yen-Kuan Wu
120ee61 Fix unexpected exception return behavior

$ git shortlog -5 fix_exp_ret_behavior

我的版本

Jim Huang (2):
      update author list: Yen-Kuan Wu
      Merge pull request #16 from yenWu/master

yenWu (3):
      Fix unexpected intial content in user thread stack     After creation of first user-level thread, the next thread is likely triggered by exception return. However, unexpected behavior occurs while the load of xPSR due to incorrect configuration on enabling carry flags in APSR at the initial stage.
      Fix unexpected exception return behavior     This problem is the similar with commit c7f9356. Change the operation of `activate()` to omit unnecessary state switched.
      Omit unnecessary mode switch     The same problem on commit c7f9356. The implementation of context switch in "06-Preemptive" is different from previous version. It separates condition of `create_task()` into different block, so we can omit annoying checking that would trigger exception return or not and manipulate saving register on PSP directly.

Jserv 修改過的版本

Jim Huang (1):
      update author list: Yen-Kuan Wu

yenWu (4):
      Fix unexpected exception return behavior
      Fix unexpected intial content in user thread stack
      Eliminate unnecessary state switching
      Eliminate unnecessary mode switching

內文每行最多 72 字

排版上會比較好看、整潔

我的版本

Jserv 修改過的版本

用內文解釋 what 以及 why vs. how

Good Example

Summarize changes in around 50 characters or less
 
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
 
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
 
Further paragraphs come after blank lines.
 
 - Bullet points are okay, too
 
 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here
 
If you use an issue tracker, put references to them at the bottom,
like this:
 
Resolves: #123
See also: #456, #789

我原本的commit

Author: yenWu <[e-mail]>
Date:   Wed Mar 29 02:13:31 2017 +0800

    Omit unnecessary mode switch
    The same problem on commit c7f9356. The implementation of context switch in "06-Preemptive" is different from previous version. It separates condition of `create_task()` into different block, so we can omit annoying checking that would trigger exception return or not and manipulate saving register on PSP directly.

修改過後的

Author: yenWu <[e-mail]>
Date:   Wed Mar 29 02:13:31 2017 +0800

    Eliminate unnecessary mode switching
    
    The implementation of context switch in "06-Preemptive"
    is different from "04-MutiTasking". The operation of
    context switch would depend on the current state in "04".
    In this case,"06", it split different situations into
    different blocks.
    
    Thus, the implemetation would not be the same with "04".
    More percisely, we can eliminate the operation checking
    the current state in this patch.
    
    Therefore, we can eliminate unexpected mode switching
    without checking state and just manipulate PSP to store
    registers within context switch.
    
    Resolves: #14
    See also: #15