# Git commit message 撰寫和改進實例: [mini-arm-os](https://github.com/jserv/mini-arm-os) ###### tags: `git`, `commit` ## [如何寫一個 Git Commit Message - Louie譯](https://blog.louie.lu/2017/03/21/%E5%A6%82%E4%BD%95%E5%AF%AB%E4%B8%80%E5%80%8B-git-commit-message/) * 重新建立一段程式碼的脈絡是非常浪費的事情。我們無法避免這件事情的複雜性，因此我們應將心力放在儘可能的降低複雜度。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== ## 用一行空白行分隔標題與內容 :::warning **`$ git log --oneline -5 <branch> `** :::danger 我的版本 --- ```shell= 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 ``` > 這就是沒有空行的壞處[name=Yen-Kwan Wu] Jserv 修改過的版本 --- ```shell= 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 ``` ::: :::warning **`$ git shortlog -5 fix_exp_ret_behavior`** :::danger 我的版本 --- ```shell= 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 修改過的版本 --- ```shell= 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 字 排版上會比較好看、整潔 :::danger 我的版本 --- ![](https://i.imgur.com/KSBhERN.png) Jserv 修改過的版本 --- ![](https://i.imgur.com/gnETrN4.png) ::: ## 用內文解釋 what 以及 why vs. how :::warning 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 <c14006078@gmail.com> 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 <c14006078@gmail.com> 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 ``` :::