|
代碼提交的commit info提個(gè)建議，fix的issue是哪個(gè)issue？都要有明確的鏈接。
推薦方式：
1.建立issue，說明問題的背景和原因。http://git./payment/paycenter/issues
2.提交代碼的時(shí)候commit info引入該issue
3.測(cè)試驗(yàn)證回歸以后close 這個(gè)issue
這樣就可以做到每一次提交都能追根溯源。提交代碼的commit info信息是給自己看的，也是給別人看的。內(nèi)容翔實(shí)自然最好，最基本的是一定要讓別人看懂你提交的是什么。
寫issue和單元測(cè)試很浪費(fèi)時(shí)間么？尤其是支付的代碼，到底是浪費(fèi)時(shí)間還是節(jié)約時(shí)間。
英文原文地址 https://chris./posts/git-commit/
導(dǎo)論：為什么說commit messages 很重要
如果你翻看某個(gè)git repo的log信息，你可能會(huì)發(fā)現(xiàn)它的commit messages是一團(tuán)毛線，比如，看看我在早期在Spring項(xiàng)目中提交的「稀世珍寶」:
$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"
e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing
噫。比較一下最近提交的commit messages吧:
$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"
5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage
你想讀哪一種呢？
前一種又臭又長(zhǎng)；后一種精準(zhǔn)一致。前一種來自「不假思索」，而后一種來自「精心組織」。
很多的repo的log信息都是前一種風(fēng)格，然而很多卻不是。比如Linux kernel 和 git 本身都是很好的例子。再看看Spring Boot項(xiàng)目，以及所有Tim Pope領(lǐng)導(dǎo)的項(xiàng)目吧。
這些項(xiàng)目的貢獻(xiàn)者都清楚，與項(xiàng)目開發(fā)者們(當(dāng)然也包括了自己)溝通的最好方式是構(gòu)建一個(gè)精巧的 commit messages 結(jié)構(gòu)。diff 會(huì)告訴你哪些文件改動(dòng)了，但只有commit message能告訴你其中的原因。Peter Hutterer 很好地抓住了要點(diǎn)：
重構(gòu)代碼是很浪費(fèi)時(shí)間的。這一點(diǎn)我們完全無法避免，所以我們應(yīng)該盡可能地減少它，commit messages 就是為了解決這個(gè)問題而誕生，而且，它能看出一個(gè)開發(fā)者是不是一個(gè)很好的合作者。
如果你還沒有好好想過一個(gè)好的commit message是什么樣子，那可能是因?yàn)槟銢]在git log以及相關(guān)的工具上花很多時(shí)間。有一個(gè)這樣的怪圈：因?yàn)閏ommit的歷史沒有結(jié)構(gòu)性、連續(xù)性，沒有人使用或關(guān)注這個(gè)項(xiàng)目。而又因?yàn)闆]有人使用、關(guān)注這個(gè)項(xiàng)目，commit messages的歷史一直保持著無結(jié)構(gòu)、不連續(xù)的。
但一個(gè)細(xì)心維護(hù)的log具有美感，并且能起作用。git blame, revert, rebase, log, shortlog 以及其他的子命令來源于生活。審查別人的commits，pull request是很有價(jià)值的事情，現(xiàn)在卻變成了獨(dú)立的行為。理解幾個(gè)月或幾年前這些是怎么發(fā)生的不僅是有可能的，也是有作用的。
一個(gè)項(xiàng)目的長(zhǎng)時(shí)期成功依賴于它的維護(hù)性，而項(xiàng)目維護(hù)者找不到比項(xiàng)目log更有用的工具了。花時(shí)間學(xué)習(xí)、針對(duì)性地實(shí)踐是很有用的，萬事開頭難，但一旦成為了習(xí)慣，它會(huì)成為所有參與者榮耀和生產(chǎn)力的源泉。
在這篇博客中，我提出的是維護(hù)一個(gè)健康 commit 歷史信息的基本要素： 怎么寫一個(gè)commit message。這里我不會(huì)寫其他的重要實(shí)踐，比如commit squashing。我可能會(huì)在隨后的博文中寫這些。
大多數(shù)編程語言有固有的慣例，形成了慣用的風(fēng)格，也就是命名，格式化這些。當(dāng)然這些慣例中有很多變數(shù)，但大多數(shù)程序員都同意堅(jiān)持一種風(fēng)格比每個(gè)人干自己的、一片混亂要好得多。
一個(gè)團(tuán)隊(duì) commit 的方法也是一樣。為了維護(hù)一個(gè)有效的版本歷史，團(tuán)隊(duì)首先要在commit message慣例上達(dá)成共識(shí)，最少要有下面的三項(xiàng)：
-
風(fēng)格。 標(biāo)記語法，折行長(zhǎng)度， 語法，大寫規(guī)則，標(biāo)點(diǎn)符號(hào)。明確規(guī)定這些，不留下猜測(cè)空間，盡可能的簡(jiǎn)潔。最終的結(jié)果是極其一致的log，它讓人樂于閱讀，當(dāng)然，也實(shí)現(xiàn)了基本的功能。
-
內(nèi)容。commit message的內(nèi)容應(yīng)該包含何種信息，不應(yīng)該包含何種信息。
-
元數(shù)據(jù)。 issue 的ID， pull request的數(shù)字應(yīng)該怎么記錄，索引等等。
幸運(yùn)的是，有一些完善的慣例指導(dǎo)我們寫 git commit 信息。當(dāng)然，很多都是用git命令來解決的。你不需要重新造輪子。遵循下面的七條準(zhǔn)則，你就可以像專業(yè)人士一樣commit了。
七條準(zhǔn)則，寫給力的git commit message
記著， 這都是前人智慧
-
用空行分開主題和正文
-
限制主題在50個(gè)字母
-
主題行首字母要大寫
-
不要用句號(hào)結(jié)束主題行
-
主題行用祈使語氣
-
每行72個(gè)字
-
在正文部分解釋什么，為什么，以及怎么做的
舉個(gè)例子
用不超過50個(gè)字簡(jiǎn)述一下有哪些改變
如果必要的話，寫更多的細(xì)節(jié)。每行不要超過72個(gè)字。第一行被視為 commit 信息以及余下正文的主題?？招蟹珠_概要和正文是非常必要的（除非你不寫正文）；如果你把 log, shortlog, rebase這樣的工具混著用會(huì)讓人迷惑。
解釋一下這個(gè)commit解決了什么問題。專注于為什么這么做而不是怎么做的（代碼已經(jīng)解釋了）。這個(gè)改變是否有副作用或其他不直觀的后果。這里就是解釋這些事情的地方。
空行之后還有段落。
- 要點(diǎn)符號(hào)也是可以的
- 通常用連字符，星號(hào)來表示要點(diǎn)符號(hào)。用一個(gè)空格起頭，用空行隔開，當(dāng)然，慣例沒有這么詳細(xì)
如果你用了 issue tracker， 把這些引用放在底部，就像這樣：
解決了：#123
參考： #456, #789
1. 用空行分開主題和正文
來自git commit的幫助文檔：
雖不強(qiáng)求，用一個(gè)單行（不超過50個(gè)字）概述一下改動(dòng)，跟著一個(gè)空行，更多一點(diǎn)描述，這就很好。在第一個(gè)空行上的文字會(huì)被作為commit的標(biāo)題，git中會(huì)使用到。舉個(gè)例子，git-format-patch命令可以把commit轉(zhuǎn)為郵件，標(biāo)題就會(huì)作為郵件的主題，正文就會(huì)當(dāng)做郵件的正文。
首先，并不是每一個(gè)commit都需要標(biāo)題，正文。有時(shí)候一行也可以的，特別是改動(dòng)比較小，不需要更多的信息的時(shí)候。舉個(gè)例子：
修改用戶導(dǎo)讀中的拼寫錯(cuò)誤
不需要說太多；如果讀者想知道什么拼寫錯(cuò)誤，他可以自己看改動(dòng)，即，用git show，git diff 或 git log -p
如果你在命令行終端中提交，用git commit -m 就很簡(jiǎn)單：
git commit -m"Fix typo in introduction to user guide"
但是，如果你的 commit 需要一點(diǎn)點(diǎn)解釋文字，你就需要寫正文了，比如：
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.
這個(gè)用 -m 就沒那么容易了。你需要一個(gè)合適的編輯器，如果你還沒有在終端中給 git 設(shè)置編輯器，讀Pro Git(https:///book/en/v2/Git-Tools-Revision-Selection#Basic-Client-Configuration)的這一章。
在任何情況下，看log的時(shí)候，主題和正文是分開的。這有個(gè)完整的log：
$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date: Fri Jan 01 00:00:00 1982 -0200
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.
如果是git log --oneline， 只輸出主題行：
$ git log --oneline
42e769 Derezz the master control program
或者，用git shortlog, 按照貢獻(xiàn)者分組，按行輸出主題：
$ git shortlog
Kevin Flynn (1):
Derezz the master control program
Alan Bradley (1):
Introduce security program "Tron"
Ed Dillinger (3):
Rename chess program to "MCP"
Modify chess program
Upgrade chess program
Walter Gibbs (1):
Introduce protoype chess program
git中有一些命令可以將主題和正文區(qū)分開 ----但主題、正文沒有空行可不行。
2. 限制主題在50個(gè)字母
50個(gè)字不是硬性標(biāo)準(zhǔn)，只是一個(gè)大致的準(zhǔn)則。確保主題行是可讀的，讓開發(fā)者一眼就知道有哪些改變。
小技巧：如果你概述的時(shí)候發(fā)現(xiàn)很困難。可能是因?yàn)槟阋淮?commit 太多改動(dòng)了。盡可能做到 atomic commits(每次post一個(gè)主題)
GitHub 的用戶界面很注意這些慣例。如果你超過了50個(gè)字的限制它會(huì)警告你：
github_commit_changes
超過69個(gè)字的主題就會(huì)用省略號(hào)截?cái)啵?/p>
truncate_subject
所以，盡可能不要超過50個(gè)字，把69個(gè)字符當(dāng)做上限。
3. 主題行首字母要大寫
就這么簡(jiǎn)單。主題行首字母大寫。
比如：
4. 不要用句號(hào)結(jié)束主題行
主題行結(jié)尾的句號(hào)是不必要的。而且，要少于50個(gè)字符的話，空間是很寶貴的。
比如：
5. 主題行用祈使語氣
祈使語氣意味著，以命令或指示的語氣說話或?qū)懽?。舉幾個(gè)例子：
祈使語氣聽起來有點(diǎn)粗魯；所以我們不常用。但 git commit 的主題行就很合適，一個(gè)理由是：無論何時(shí)你創(chuàng)建commit，git 本身就是祈使語氣的
比如，git merge 創(chuàng)建的默認(rèn)信息是：
Merge branch 'myfeature'
當(dāng)你用 git revert 時(shí):
Revert "Add the thing with the stuff"
This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.
在 GitHub 上pull request 點(diǎn)「Merge」按鈕的時(shí)候:
Merge pull request #123 from someuser/somebranch
所以，當(dāng)你以祈使語氣 commit messages 的時(shí)候，你遵循的正是 git 自身的傳統(tǒng)。 比如：
-
Refactor subsystem X for readability (重構(gòu)子系統(tǒng)X，增強(qiáng)可讀性)
-
Update getting started documentation (更新初始文檔)
-
Remove deprecated methods (移除將廢棄的函數(shù))
-
Release version 1.0.0 (發(fā)布 1.0.0 版本)
用這種方式一開始可能有點(diǎn)不適應(yīng)。我們更習(xí)慣于指示性的語氣，像是報(bào)告事實(shí)一樣。 因此，commit messages 經(jīng)常像這樣：
有時(shí)候 commit messages 只是在描述 commit 的內(nèi)容:
為了消除困惑，這有一條簡(jiǎn)單的準(zhǔn)則：
**一個(gè)合理格式化后的 git commit 主題行總能替換到下面的句子中: **
如果應(yīng)用了，這個(gè) commit 會(huì)你的主題行
比如：
-
如果應(yīng)用了，這個(gè) commit 會(huì)重構(gòu)子系統(tǒng)X，增強(qiáng)可讀性
-
如果應(yīng)用了，這個(gè) commit 會(huì)更新初始文檔
-
如果應(yīng)用了，這個(gè) commit 會(huì)移除將廢棄的函數(shù)
-
如果應(yīng)用了，這個(gè) commit 會(huì)發(fā)布 1.0.0 版本
-
如果應(yīng)用了，這個(gè) commit 會(huì)合并來自 user/branch 的pull request #123
注意，在非祈使的條件下就不適用了，如：
-
If applied, this commit will fixed bug with Y
-
If applied, this commit will changing behavior of X
-
If applied, this commit will more fixes for broken stuff
-
If applied, this commit will sweet new API methods
記著，在主題行中用祈使句很重要。在寫正文的時(shí)候就不用在乎這個(gè)限制了。
6. 每行72個(gè)字
Git 不會(huì)自動(dòng)折行，當(dāng)你寫 commit message 的正文時(shí)，你必須考慮右邊的長(zhǎng)度，人工地折行。
推薦每72個(gè)字就折行，讓 git 滿足80個(gè)字的限制的時(shí)候有足夠的空間縮進(jìn)正文。
一個(gè)好的編輯器就起作用了。配置 Vim 是很簡(jiǎn)單的, 比如，設(shè)置折行為72個(gè)字。一般來說，IDE在智能折行上表現(xiàn)就很糟糕了（在近期的版本中，IntelliJ IDEA 終于有了比較好的支持）
7. 在正文部分解釋什么，為什么，以及怎么做的
這一Bitcoin Core 的commit很好的說明了什么改動(dòng)了，以及為什么改動(dòng)：
commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date: Fri Aug 1 22:57:55 2014 +0200
Simplify serialize.h's exception handling
Remove the 'state' and 'exceptmask' from serialize.h's stream
implementations, as well as related methods.
As exceptmask always included 'failbit', and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead
code).
As a result, good() is never reached after a failure (there are
only 2 calls, one of which is in tests), and can just be replaced
by !eof().
fail(), clear(n) and exceptions() are just never called. Delete
them.
看看完整的 diff，想想這個(gè) commit message 給隊(duì)友以及后繼的開發(fā)者節(jié)約了多少時(shí)間吧。如果他沒有這樣寫，這些變動(dòng)可能就永遠(yuǎn)都看不到了。
在大多數(shù)情況下，你可以忽略變動(dòng)的細(xì)節(jié)，代碼基本上是不言自明的（如果代碼很復(fù)雜，就需要文字解釋，這就需要注釋了），首先說清楚改動(dòng)的原因----改動(dòng)前代碼是怎么工作的（有什么問題），現(xiàn)在又是怎樣的，你為什么要解決這個(gè)問題，又是怎么解決的。
未來感謝你的軟件維護(hù)者可能就是你自己！
小技巧
享受命令行，遠(yuǎn)離IDE
git 有很多子命令是不無理由的，擁抱命令行是明智的選擇。Git 太TM強(qiáng)大了；IDE 當(dāng)然也是，但每一種有不同的方式。我每天都用IDE（IntelliJ IDEA），也用其他（如Eclipse）， 但我從沒見過能與強(qiáng)大、簡(jiǎn)單的終端媲美的集成了git的IDE(你懂得)
誠然，集成了 git 的IDE 很難得，比如可以刪除文件時(shí)調(diào)用git rm，重命名文件是調(diào)用相關(guān)的git命令。但要完成 commit, merge, rebase，或復(fù)雜的歷史版本分析時(shí)，IDE就捉襟見肘了。
要想充分發(fā)揮 git 的威力，那就必須命令行滿屏幕飛了。
記著，不管是用 Bash 或是 Z shell，Tab 補(bǔ)全能讓你減輕記命令的痛苦。
讀《Pro Git》
Pro Git(https:///book/en/v2)是在線，免費(fèi)的，真是極好的。好好利用！
|
