Git 規范

所有使用了本規范的項目，必須嚴格規范操作，否則不予以合并代碼、提測、打包上線等后續操作。

基本要求

• 所有commit必須有注釋，內容必須按照注釋格式嚴格執行！
• 合理控制提交內容的顆粒度，一次commit含一個獨立功能點。嚴禁一次提交涵蓋多個功能項。
• 正確為每個項目設置Git提交用到的user.name和user.email信息，以公司郵箱為準，不可隨意設置以影響無法正確識別。 查看當前項目配置信息的命令：git config -l

版本號(tag)

• 版本號(tag)命名規則：主版本號.次版本號.修訂號，如2.1.13。(遵循GitHub語義化版本命名規范)
• 版本號僅標記于master分支，用于標識某個可發布/回滾的版本代碼
• 對master標記tag意味著該tag能發布到生產環境
• 對master分支代碼的每一次更新(合并)必須標記版本號
• 僅項目管理員有權限對master進行合并和標記版本號

項目權限

Git權限分管理員、開發者、瀏覽者三種類型，可以在Gitlab上設置每個項目的項目權限

gitlab_role.png

• 瀏覽者(Guest)只能瀏覽代碼，無push、pull request等所有寫權限
• 開發者(Developer)擁有瀏覽、push非主分支、提交pull request工單權限
• 管理員(Master)擁有建立和管理Git項目、合并分支和代碼、給master打tag版本號等權限

分支使用

• 每個Git項目固定含有上述所有分支類型。主分支master和develop是保護分支，只能進行合并請求，均不可直接提交代碼。
• 功能需求或常規Bug修復，請從develop拉取feature分支；線上緊急問題修復，請從master拉取hotfix分支。

代碼提交

• 一個提交就代表解決一個問題
• 大問題適當地分解為多個小問題，以便每次小型提交都更易于理解

代碼合并

將開發完畢的分支，拉取develop最新代碼，merge并解決沖突后，之后在對應的feature分支創建并提交到develop分支，并自動觸發merge request請求，然后進行code review，確認無誤后再合并。

注意：

• 每個merge request不要包含不相關的功能
• merge request提交后需要及時跟蹤動態，包括通過、打回等
• 該功能進入提測流程后，需刪除之前的功能分支

注釋格式

每次提交，Commit message 都包括三個部分：Header，Body 和 Footer。

code_comment.png

其中，Header 是必需的，Body 和 Footer 可以省略。不管是哪一個部分，任何一行都不得超過72個字符。這是為了避免自動換行影響美觀。

Header

Header部分只有一行，包括三個字段：type（必需）、scope（可選）和subject（必需）。

• type用于說明 commit 的類別，只允許使用下面7個標識。

• feat：新功能（feature）

• fix：修補bug

• docs：文檔（documentation）

• style： 格式（不影響代碼運行的變動）

• refactor：重構（即不是新增功能，也不是修改bug的代碼變動）

• test：增加測試

• chore：構建過程或輔助工具的變動

• scope用于說明 commit 影響的范圍，比如數據層、控制層、視圖層等等，視項目不同而不同。

• subject是 commit 目的的簡短描述，不超過50個字符。

以動詞開頭，使用第一人稱現在時，比如change，而不是changed或changes
第一個字母小寫
結尾不加句號（.）

Body

Body 部分是對本次 commit 的詳細描述，可以分成多行, 有兩個注意點:

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

• 應該說明代碼變動的動機，以及與以前行為的對比;

Footer

Footer 部分只用于兩種情況:

• 如果當前代碼與上一個版本不兼容，則 Footer 部分以BREAKING CHANGE開頭，后面是對變動的描述、以及變動理由和遷移方法;

• 如果當前 commit 針對某個issue，那么可以在 Footer 部分關閉這個 issue (Closes #123, #245, #992), GitHub這個功能很好用；

Revert

還有一種特殊情況，如果當前 commit 用于撤銷以前的 commit，則必須以revert:開頭，后面跟著被撤銷 Commit 的 Header。

為什么要約定注釋格式？ 1. 加快 Reviewing Code 的過程 2. 幫助我們寫好 release note 3. 5年后幫你快速想起來某個分支，tag 或者 commit 增加了什么功能，改變了哪些代碼 4. 讓其他的開發者在運行 git blame 的時候想跪謝 5. 其他小伙伴不會出現想抽你的沖動 6. 總之，一個好的提交信息，會幫助你提高項目的整體質量

Git Flow

簡介

Git Flow是構建在Git之上的一個組織軟件開發活動的模型，是在Git之上構建的一項軟件開發最佳實踐。Git Flow是一套使用Git進行源代碼管理時的一套行為規范和簡化部分Git操作的工具。

gitflow_main.png

工作流中涉及到的角色介紹：

• 功能開發者：模塊中功能的開發人員；
• 開發管理員：由項目模塊開發的小組長（team leader）擔當；
• 測試管理員：由測試團隊指定人員擔當；
• 發布管理員：由生產環境發布團隊指定人員擔當；

分支說明

分支約定

Git Flow有主分支和輔助分支兩類分支。其中主分支用于組織與軟件開發、部署相關的活動；輔助分支組織為了解決特定的問題而進行的各種開發活動。

主分支

git_master.png

主分支是所有開發活動的核心分支。所有的開發活動產生的輸出物最終都會反映到主分支的代碼中。主分支分為master分支和develop分支。

master 分支

• master分支存放的是隨時可供在生產環境中部署的穩定版本代碼
• master分支保存官方發布版本歷史，release tag標識不同的發布版本
• 一個項目只能有一個master分支
• 僅在發布新的可供部署的代碼時才更新master分支上的代碼
• 每次更新master，都需對master添加指定格式的tag，用于發布或回滾
• master分支是保護分支，不可直接push到遠程倉master分支
• master分支代碼只能被release分支或hotfix分支合并

develop 分支

• develop分支是保存當前最新開發成果的分支
• 一個項目只能有一個develop分支
• develop分支衍生出各個feature分支
• develop分支是保護分支，不可直接push到遠程倉庫develop分支
• develop分支不能與master分支直接交互

每次將develop分支上的代碼合并回master分支時，我們都可以認為一個新的可供在生產環境中部署的版本就產生了。基于此，理論上說，每當有代碼提交到master分支時，我們可以使用Git Hook觸發軟件自動測試以及生產環境代碼的自動更新工作。這些自動化操作將有利于減少新代碼發布之后的一些事務性工作。

只有開發管理員有合并的權限

輔助分支

git_assist.png

輔助分支是用于組織解決特定問題的各種軟件開發活動的分支。輔助分支主要用于組織軟件新功能的并行開發、簡化新功能開發代碼的跟蹤、輔助完成版本發布工作以及對生產代碼的缺陷進行緊急修復工作。這些分支與主分支不同，通常只會在有限的時間范圍內存在。跟“歷史性”分支相反，這三類分支都是短期分支，針對他們的工作內容完成后，一般都要進行刪除。

工作內容完成的標識有兩個：開發完成、合并完成，缺一不可。

輔助分支包括：

• 用于開發新功能時所使用的feature分支
• 用于輔助版本發布的release分支
• 用于修正生產代碼中的缺陷的hotfix分支

以上這些分支都有固定的使用目的和分支操作限制。從單純技術的角度說，這些分支與Git其他分支并沒有什么區別，但通過命名，我們定義了使用這些分支的方法。

feature 分支

使用規范：

• 分支的命名格式必須是版本號-功能名，例如v1.0.0-login
• develop分支的功能分支
• feature分支使用develop分支作為它們的父類分支
• 以功能為單位從develop拉一個feature分支
• 每個feature分支顆粒要盡量小，以利于快速迭代和避免沖突
• 當其中一個feature分支完成后，它會合并回develop分支
• 當一個功能因為各種原因不開發了或者放棄了，這個分支直接廢棄，不影響develop分支
• feature分支代碼可以保存在開發者自己的代碼庫中而不強制提交到主代碼庫里
• 由每組開發管理員負責把所有feature分支開發完成的代碼合并到develop分支
• feature分支只與develop分支交互，不能與master分支直接交互

如有幾個同事同時開發，需要分割成幾個小功能，每個人都需要從develop中拉出一個feature分支，但是每個feature顆粒要盡量小，因為它需要我們能盡早merge回develop分支，否則沖突解決起來就沒完沒了。同時，當一個功能因為各種原因不開發了或者放棄了，這個分支直接廢棄，不影響develop分支。

release 分支

使用規范：

• 命名規則：release/*，“*”以本次發布的版本號為標識
• release分支主要用來為發布新版的測試、修復做準備
• 當需要為發布新版做準備時，從develop衍生出一個release分支
• release分支可以從develop分支上指定commit派生出
• release分支測試通過后，合并到master分支并且給master標記一個版本號
• release分支一旦建立就將獨立，不可再從其他分支pull代碼
• 必須合并回develop分支和master分支

release分支是為發布新的產品版本而設計的。在這個分支上的代碼允許做小的缺陷修正、準備發布版本所需的各項說明信息（版本號、發布時間、編譯時間等）。通過在release分支上進行這些工作可以讓develop分支空閑出來以接受新的feature分支上的代碼提交，進入新的軟件開發迭代周期。

當develop分支上的代碼已經包含了所有即將發布的版本中所計劃包含的軟件功能，并且已通過所有測試時，我們就可以考慮準備創建release分支了。而所有在當前即將發布的版本之外的業務需求一定要確保不能混到release分支之內（避免由此引入一些不可控的系統缺陷）。

成功的派生了release分支，并被賦予版本號之后，develop分支就可以為“下一個版本”服務了。所謂的“下一個版本”是在當前即將發布的版本之后發布的版本。版本號的命名可以依據項目定義的版本號命名規則進行。

hotfix 分支

使用規范：

• 命名規則：hotfix/*，“*”以本次發布的版本號為標識
• hotfix分支用來快速給已發布產品修復bug或微調功能
• 只能從master分支指定tag版本衍生出來
• 一旦完成修復bug，必須合并回master分支和develop分支
• master被合并后，應該被標記一個新的版本號
• hotfix分支一旦建立就將獨立，不可再從其他分支pull代碼

除了是計劃外創建的以外，hotfix分支與release分支十分相似：都可以產生一個新的可供在生產環境部署的軟件版本。

當生產環境中的軟件遇到了異常情況或者發現了嚴重到必須立即修復的軟件缺陷的時候，就需要從master分支上指定的TAG版本派生hotfix分支來組織代碼的緊急修復工作。

這樣做的顯而易見的好處是不會打斷正在進行的develop分支的開發工作，能夠讓團隊中負責新功能開發的人與負責代碼緊急修復的人并行的開展工作。

版本管理

我們使用 Git Flow 來進行版本管理控制，它相對于 GitHub Flow 更適合在產品開發中快速迭代，這種代碼管理模式應該已經廣泛使用了。

另外，我們鼓勵使用 Git 客戶端 SourceTree，它集成了 Git Flow 的一些基本操作。如果嚴格遵循 Git Flow 的流程進行版本管理控制，那么我們只用管開始和結束一個 Feature/Release/Hotfix，基本上是不用手動 merge 分支的。

gitflow_branch.jpg

新功能開發流程

1. 從 develop 分支創建 feature 分支；
2. 開發調試完將 feature 分支提交到遠程版本庫；
3. 提交 pull request 請求合并到 develop 分支；
4. 相關負責人 code review 后如果同意合并后，刪除遠程 feature 分支，如果不同意，重新修改后再上傳 feature 分支請求 pull request。

Pull Request

Pull Request是當功能開發者完成一個新功能后向項目維護者發送合并請求通知的機制。它的使用過程如下：

pull_request.png

1. 功能開發者可以通過Gitlab頁面發送pull request
2. 開發管理員自己或組織其他的團隊成員審查、討論和修改代碼
3. 開發管理員合并新增功能分支到develop分支，然后關閉pull request，并且可以選擇刪除新增分支

工作流程

1?? 由開發管理員負責在Gitlab上創建空白的倉庫，并clone到本地，在sourcetree的git flow菜單中選擇初始化倉庫，并push到遠端。

init_repo.png

2?? 在Gitlab上設置保護分支，把master、develop分支保護起來，只有指定人可push。

3?? 功能開發者clone代碼到本地，先在sourcetree的git flow菜單中選擇初始化倉庫。

init_repo.png

4?? 然后再開始新建功能分支，進行開發工作。

new_feature.png

5?? 新功能開發全部完成或部分完成后，功能開發者把最新代碼push到遠端同樣的新功能分支里，并在Gitflow發起pull request給開發管理員

6?? 開發管理員review代碼，選擇合并代碼到develop，并可選擇刪除已經合并的新功能分支

7?? 當開發管理員處理完合并請求后，開發者,切換到develop分支，直接刪除自己的本地分支及遠程分支，不要點擊完成(Finish Feature)，此時開發者pull遠端develop分支最新代碼即可，可忽視本地的push提醒。

delete_feature1.png

delete_feature2.png

8?? release、hotfix分支和feature分支操作類似。

9?? 不可點擊完成新功能、完成發布版本、完成修復補丁，因為這樣會導致自動合并代碼到master或develop分支

finish_feature_no.png

SourceTree mac版本下載地址

SourceTree_2.3.1.zip

鏈接:https://pan.baidu.com/s/1XHFvLh5MueebYjjGrEVcdQ 密碼:opjd

SourceTree win版本下載地址

SourceTree2480.zip

鏈接:https://pan.baidu.com/s/1z6UC7LrzJLNn9yeQnxoWyg 密碼:7uac

windows下使用sourcetree需要安裝一下軟件，請在安裝sourcetree前安裝好：

Git-2.17.0-64-bit.exe

鏈接:https://pan.baidu.com/s/1q0WQw03U9oCmhN5Fii7PNQ 密碼:ab2n

mercurial-4.4.1-x64.msi

鏈接:https://pan.baidu.com/s/1PBIRFFMPsIe3MoV_42dDzg 密碼:nvkx

安裝SourceTree打開后會提示你Atlassian需要注冊，這家軟件公司在澳大利亞，所以注冊時需要翻墻，才能注冊成功，這里提供一個跳過注冊的方法

1. 找到目錄：C:\Users\用戶\AppData\Local\Atlassian\SourceTree
2. 新建accounts.json文件里面輸入下面代碼塊內容后，重新打開，就不會提示注冊了！

[  
  {  
    "$id": "1",  
    "$type": "SourceTree.Api.Host.Identity.Model.IdentityAccount, SourceTree.Api.Host.Identity",  
    "Authenticate": true,  
    "HostInstance": {  
      "$id": "2",  
      "$type": "SourceTree.Host.Atlassianaccount.AtlassianAccountInstance, SourceTree.Host.AtlassianAccount",  
      "Host": {  
        "$id": "3",  
        "$type": "SourceTree.Host.Atlassianaccount.AtlassianAccountHost, SourceTree.Host.AtlassianAccount",  
        "Id": "atlassian account"  
      },  
      "BaseUrl": "https://id.atlassian.com/"  
    },  
    "Credentials": {  
      "$id": "4",  
      "$type": "SourceTree.Model.BasicAuthCredentials, SourceTree.Api.Account",  
      "Username": "",  
      "Email": null  
    },  
    "IsDefault": false  
  }  
]

推薦工具

• Git Flow 擴展 Git Flow模型提出者nvie寫的Git命令集擴展，提供了極出色的命令幫助以及輸出提示。支持OSX，Linux和Windows平臺。參考：git-flow 備忘清單

參考資料

Git 工作流與規范
Commit message 和 Change log 編寫指南