［譯］AngularJS Git提交資訊規範

山河永寂發表於2016-01-10
AngularJSGit

  • 目標

    • 生成 CHANGELOG.md

    • 識別不重要的提交

    • 在瀏覽 Git 歷史時提供更多資訊

  • 格式化提交資訊

    • 恢復(Revert)

    • 資訊頭部

        - 必需<type>
  - 必需<scope>
  - <subject>文字

    • 資訊主體

    • 資訊尾部

        - 重大更改(Breaking changes)
  - 引用討論(Referencing issues)

目標

  • 能夠通過指令碼生成 CHANGELOG.md

  • 能讓 git bisect 過程忽略不重要的提交

  • 在瀏覽歷史時提供更好的資訊

生成 CHANGELOG.md

我們在 changeling 裡使用這三個標誌: new features, bug fixes, breaking changes.
在做一個發行版的時候，這個列表可以通過指令碼來生成，通過關聯這些相關的提交。
自然，你可以在實際發行之前編輯這些變更日誌，但是這樣子可以很容易的生成骨架。

列出自最近一次發行以來所有的主體（提交資訊第一行）

>> git log <last tag> HEAD —pretty=format:%s

在本次發行內的新功能

>> git log <last release> HEAD —grep feature

識別不重要的提交

通常有很多的Formatting changes(adding/removing spaces/empty lines, indentation), missing semicolons, comments.所以當你查詢一些變更的時候，你可以忽略這些提交 – 這些提交裡面沒有業務邏輯變更。

當二分查詢的時候，你可以忽視這些提交通過鍵入以下命令：

>> git bisect skip $(git rev-list —grep irrelevant <good place> HEAD)

在瀏覽歷史時提供更多資訊

這將會增加一種“context”資訊
看這些資訊（通過檢視最近的 angularjs 的提交資訊）

  • Fix small typo in docs widget (tutorial instructions)

  • Fix test for scenario.Application – should remove old iframe

  • docs – various doc fixes

  • docs – stripping extra new lines

  • Replaced double line break with single when text is fetched from Google

  • Added support for properties in documentation

所有這些資訊都嘗試去表明更改的位置，但是它們沒有使用公共的規範
再看看這些資訊：

  • fix comment stripping

  • fixing broken links

  • Bit of refactoring

  • Check whether links do exist and throw exception

  • Fix sitemap include (to work on case sensitive linux)

你能猜出這裡面到底裝了些什麼？這些資訊缺乏重點。
也許還有這些程式碼：docs, docs-parser, compiler, scenario-runner, …
我知道，你可以通過檢視哪些檔案被改變來確定這個提交到底做了什麼，但是這樣子太麻煩了。
當檢視 git 歷史資訊的時候我們可以看到大家都在努力保持一致，但是缺少一個公共規範。

提交資訊的格式化

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

提交資訊的任意一行都不能超過100個英文字元！這個能讓資訊在 github 上和 git 工具裡更容易檢視。

恢復

如果提交是用於恢復一個更早的提交，這個頭部應該以“revert:”開始，接下來是被恢復提交的頭部，在主體內應該寫“This reverts commit <hash>.”，hash 的位置就是被恢復提交的 sha 值

資訊頭部

資訊頭部應該是包含改變的一條單行簡要描述，包括一個型別，一個可選的範圍和一個主題

必需的<type>
這是用於說明提交的型別，下列是7個標誌。

  • feat: 新功能

  • fix : 修補bug

  • docs: 文件

  • style: 格式化，缺少分號等

  • refactor

  • test: 增加缺少的測試

  • chore 維護

必需的<scope>
範圍可以是任何制定的提交更改的地方。例如 $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView等等
<subject>文字
這是變更的簡單描述

  • 以動詞開頭，使用第一人稱現在時，比如change，而不是changed或changes

  • 第一個字母小寫

  • 結尾不加句號

資訊主體

這部分是對本次提交的詳細描述，可以分成多行

  • 使用第一人稱現在時，比如使用 change 而不是 changed 或者 changes。

  • 說明程式碼變更的冬季，以及和以前程式碼的對比

資訊尾部

只有兩種情況：
不相容變動
所有不相容變動應該被列為不相容變動塊放在資訊尾部，應該以“BREAKING CHANGE:”開始，後面是對變動的描述，以及變動的動機和遷移方法
引用討論
如果當前提交是針對某個討論，那麼可以在尾部關閉這個討論
Closes #234
或者同時關閉多個討論
Closes #123, #245, #992

相關文章