Git新手教程-日誌提交規範(五)補充

前言

若是你們學習了以前的文章Git新手教程-向倉庫中添加commit(五),我相信你們確定還會爲如何提交一個比較規範的 commit 信息而煩惱,雖然咱們在上面的文章中介紹了兩篇相關的文章:html

我相信你們確定仍是會疑惑。這裏就以我以前理解的 commit 規範爲列子。但願起到一個拋磚引玉的做用。畢竟 commit 信息只是人爲規範。不一樣公司,不一樣項目,不一樣人有着本身的看法。由於做者自己是一名愛崗敬業的 Android 程序員,可能提交日誌相對於傾向於移動端,因此若是你們有更好的提交日誌分享。這裏很是歡迎在評論中看到你的回答~程序員

反面例子

在瞭解個人提交規範以前,咱們來看一些反面的 commit 信息:數據庫

  • 修改登陸界面的Bug
  • 修改空指針異常
  • 增長提示
  • 代碼優化
  • 調整UI

從上述 commit 信息中,我相信你們已經看出一些問題,就是這些 commit 消息意圖都指代不明。咱們根本能從這些 commit 中知道,究竟是爲了解決什麼問題而提交的。性能優化

就拿 "修改登陸界面的Bug」 來講,到底登陸界面有什麼 Bug ?就不能寫清楚嗎? "修改空指針異常」,哪一個界面的空指針?致使空指針的緣由,又是什麼呢?bash

這個時候你可能會說:"咱們能夠查看 commit 對應所提交的文件, 你看修改的文件不就知道我幹了什麼嗎?" 對!好像從代碼中我能知道你幹了什麼,可是我懶啊,我不想看你寫的代碼,我只想知道你提交這個 commit 的原由及解決方式,對於你的代碼我不想關心。工具

固然這並非懶不懶的緣由,一個好的 commit 就像指路牌同樣,總能簡單明確的告訴咱們明確的信息。特別是在項目後期維護與迭代中,咱們能也根據這些 commit 快速鎖定問題。總之一個良好的 commit 有着不容小覷的做用,那接下來看看關於個人日誌提交規範吧。post

關於個人日誌提交規範

整個信息結構由兩個不一樣的部分構成,這些部分由空行分割:標題、可選的消息體。性能

標題

消息體
複製代碼

具體的結構以下所示:學習

類型:【項目組名稱/簡稱】【Bug/需求Id】【有無風險】【有無依賴】【需求/Bug/更改描述】

   - 分析:
   - 風險:
   - 解決方案:
   - 測試建議:
   - 適用範圍:
   - 測試機型:
   - 自測結果:
複製代碼

標題

標題通常狀況下,都不超過 50 個字符,末尾不加句號。若是50個字符,還不能很清楚的描述你此次的 commit 。那麼你能夠在消息體中具體描述。接下來咱們就分別介紹標題中涉及到的選項。測試

類型(必填)

類型位於在標題內,有如下幾種可能:

  • Feat(feature):新功能
  • Fix:bug 修復
  • Docs:文檔修改,註釋更改
  • Style:修改代碼格式、補充分號等
  • Refactor:代碼重構
  • Test:測試添加、測試重構等,代碼無變更
  • Chore:構建任務更新,程序包管理器配置等,代碼無變更。
  • Revert:恢復先前的提交

添加類型主要的目的,不只是爲了幫助本身或其餘人理解對應 commit 主要乾了什麼,還能夠篩選同類型的提交。好比咱們能夠篩選出全部的feat(新功能) ,那麼在發佈新版本的時候,咱們能更好的書寫版本發佈日誌。

項目組名稱/簡稱(非必填)

填寫項目組名稱或者簡稱,可是通常建議簡稱。這樣咱們就能迅速找到該項目組提交的代碼。代碼若是出現了問題,咱們也能快速定位到哪一個組該背鍋,你說是不?

Bug/需求 Id(必填)

Bug/需求Id 須要對應你本身的公司項目的管理工具,如 JIRAIcafeTeambition 等,這裏將 Id 放在標題內,也是考慮到起到一個快速定位的做用,放在標題處顯眼!!!

有無風險(非必填)

在實際的項目開發中,每每會涉及到系統版本兼容問題、數據庫遷移問題、特定版本API使用問題、項目新老版本適配問題等其餘風險。在項目開發中,咱們須要將這些風險明確指出。 若是你此次提交內容中包含一些風險因數,那麼這裏咱們就能夠添加【有風險】,具體什麼風險,咱們能夠在消息體中的風險模塊中具體描述。

有無依賴(非必填)

這裏有無依賴是指的是否依賴其餘模塊,若是公司的項目很大,通常都會涉及到多模塊,不一樣模塊之間確定會有依賴關係。這裏舉一個簡單的例子,假如咱們開發的是一個商場項目,如今咱們是基礎業務組,如今有一個需求#331,須要讓咱們實現點擊某個商品,完成購物,那麼咱們確定會涉及到用戶支付,而支付又是支付組在負責。那麼在進行 commit 提交時,咱們就能夠添加【依賴支付模塊】,這樣作不只可讓咱們的測試工程師清晰的知道需求所包含的模塊。也能在功能出現問題的時候,可以找準方向,對症下藥。

需求/Bug/更改描述(必填)

在標題處,經過對需求、Bug、更改的簡短的描述,也能快速的讓其餘人知道咱們這個提交究竟是作什麼的。通常狀況下,描述以動詞開頭,好比新增某個功能、移除了什麼、更新了什麼、重命名了什麼、移動了什麼等等。總之簡短扼要就好了,若是你以爲簡短的語句,並不能很好的概況所須要解決的問題。那麼你能夠在消息體中在進行詳細的描述。

消息體(選填)

消息體,能夠看作對標題的細緻描述。並非全部的提交信息都複雜到須要消息主體,所以這是選填內容,僅在提交信息須要必定的解釋和語境時使用。消息體主要用於解釋與完善提交任務的內容和緣由。接下來咱們就來分別講解消息體中包含的其餘選項。

分析(選填)

分析模塊:主要對需求的場景分析Bug出現的緣由進行介紹。這裏分析的做用很是重要。不只能驗證開發人員對功能或 Bug 的理解程度,還能減小公司新來的小夥伴閱讀代碼,瞭解業務的時間。

風險(選填)

風險模塊:是對標題中的【有風險】進行詳細的闡述。具體怎麼描述,根據本身的實際項目而定。

解決方案 (選填)

解決方案模塊:該模塊主要針對於性能優化Bug修復。主要用於解釋所解決的問題的方式方法。

測試建議 (選填)

測試建議模塊:該模塊主要針對於新功能開發Bug修復。在該模塊中,咱們能夠詳細說明,有哪些界面,哪些功能須要測試。這對於採用自動化打包工具(好比 Jenkins)的 團隊特別有用,由於咱們的測試小夥伴能夠在使用自動化打包工具打包時,就能看見你提交的 commit ,那麼根據你提供的測試建議,他們也能知道到測試過程當中須要着重測試的地方以及須要注意的地方。

適用範圍 (選填)

適用範圍模塊:該模塊主要包含的內容 取決於 commit 的內容是針對某一系統版本,針對於特定設備,仍是包含全部。這裏能夠根據自身的提交來填寫。

測試機型(選填)

由於做者我是一名 Android 程序員,因此這裏單獨抽出了測試機型,也是合情合理的。

測試機型模塊:該模塊主要包含內容爲你當前項目所運行的設備機型。固然由於 Android 的碎片化,在實際的項目開發中,咱們可能會考慮不一樣廠商下的不一樣手機型號下的不一樣系統版本適配的問題。因此這裏的機型,並非惟一值,仍是要根據自身的提交來填寫。

(PS:Android 程序員就是這麼辛苦,爲何工資沒有 IOS 的高,不開心。)

自測結果

自測結果模塊:完成新功能或修改 Bug 後,填寫自測結果。不只是對咱們本身工做成果的驗收,還能減小由於代碼的問題而增長的返工次數,雖然咱們不能保證本身測試後,就沒有任何的問題了,可是至少咱們的態度是端正的對吧~

例子展現

瞭解了規範以後,咱們來看看經常使用的 commit 書寫。

功能開發

對於功能開發,咱們通常須要標題與消息體。具體例子以下所示:

Feat:【CT】【#1345】【無風險】【無依賴】【優化了優惠券的展現方式】

   - 分析:顧客帳戶的優惠券太多,若是按照原來的一個個展現,顯示比較混亂。因此須要將同類型的劵合併展現。
   - 風險:無
   - 解決方案:將同類型的優惠券合併展現
   - 測試建議:測試優惠券展現界面
   - 適用範圍:全部版本
   - 測試機型:oppo、miui、huawei
   - 自測結果:經過
複製代碼

在該 commit 中,標題中的數據以下:

  • Feat:功能類型
  • 【CT】:爲項目組名稱/簡稱
  • 【#1345】:爲需求ID
  • 【無風險】:有無風險、無則顯示爲無
  • 【無依賴】:有無依賴,無則顯示爲無
  • 【優惠券展現優化】:功能的簡要描述,以動詞開頭

消息體中的數據,比較明顯,這裏你們能夠本身的項目需求來填寫。

Bug 修改

Bug 修改的 commit 信息 與功能基本開發同樣,惟一的區別就是 commit 的 類型爲 Fix。具體例子以下

Fix:【FS】【#123】【無風險】【無依賴】【修改登陸界面密碼框輸入空字符串致使的程序崩潰】

   - 分析:由於在輸入密碼時,沒有對數據進行判空處理,因此會致使空指針異常。
   - 風險:無
   - 解決方案:對密碼字符串進行判空處理,若是爲空則提示用戶輸入密碼。
   - 測試建議:對bug進行回顧測試
   - 適用範圍:全部版本
   - 測試機型:oppo、miui、huawei
   - 自測結果:經過
複製代碼

文檔與樣式修改

由於文檔的編寫與文檔的樣式修改並不會影響主體的代碼,因此咱們不用像新功能開發與bug修改那樣書寫很完整的 commit 信息,只須要簡明扼要的描述咱們修改的內容就能夠了。

文檔修改:

Docs: 修改了 MainActiviy 類中的方法註釋
複製代碼

或者

Docs: 添加了使用指南的文檔
複製代碼

格式樣式修改:

Style:修改了 MainActiviy 類中的格式
複製代碼

其餘注意事項

在進行 commit 時,咱們仍然須要注意如下事項:

  • 咱們須要保證對項目的 commit 是針對新增某一個功能或修復某一個Bug 所做的提交。而不是該提交中包含對其餘功能模塊的修改。
  • 咱們儘可能建立短小而明確的 commit ,什麼是短小而明確的 commit 呢?其實很簡單,咱們的 commit 所涉及的文件最好不要超過10多個文件或數百行的代碼更改。咱們的 commit 要有針對性。

題外話

雖然瞭解一個項目的最好的方式就是 read the fucking source code,可是若是項目自己有着良好的 commit ,總會給咱們帶來事半功倍的效果對吧。從一些小事嚴格要求本身,我相信之後總會爲咱們帶來一些特別的驚喜~~

相關文章
相關標籤/搜索