程式碼倉庫建立規範
程式碼倉庫建立規範
1、 專案建立需符合Group
規範。
2、 建立專案必須新增Project description
說明。
3、 每個專案都需要README.md
檔案。
4、 除文件說明型別倉庫,所有程式碼倉庫都需要.gitignore
。
注:有模板的專案,要以統一的模板建立專案
Groups使用規範
Group 分為 rule(技術行為規範)、lab(技術預研)、common(基礎庫)、realicloud(基礎平臺)、realibox(產品)、customer(定製化開發專案)
目錄結構及許可權介紹
-
rule - Internal
-
- 主要用於存放技術行為規範相關資料
-
lab - Internal
-
- 主要用於存放技術預研,比如shader預研、售前demo技術預研等。
-
common - Internal
-
- 主要用於存放公共元件庫,基礎演算法庫
-
rexxxud - Private
-
- 主要用於存放底層基礎能力平臺相關微服務,如PaaS層的介面、閘道器鑑權服務等。
-
rexxxb - Private
-
- 主要存放產品相關業務程式碼,如應用中心小程式等。
-
customer - Private
-
- 主要存放客戶制定化開發專案程式碼。
許可權說明:gitlab主要包括三種許可權Private、Internal、Public,分別為只對組內使用者開放、註冊使用者可見和公開,公司gitlab一般不使用Public
關聯倉庫的管理
涉及內部倉庫之間的引用採用 submodule 進行版本管理,對於可開源釋出的版本管理採用包管理,比如pip、npm、go get。
主專案管理形式如下:
A(主專案) --> B(common公共模組)
|
|---> C(包管理)
|
|---> D(其他倉庫)
將引用專案作為submodule新增到主專案中:
# 新增submodule
$ git submodule add <遠端引用模組倉庫地址>
子專案版本管理和主專案版本管理是分發的,主專案中的子專案更新需要手動操作:
# 更新子模組 $ git submodule update --init
README檔案規範
README檔案結構如下:
<專案簡介/Introduction>
<快速使用/Quick start>
<文件說明/Documentation>
Introduction
用於闡述專案基本情況和功能(是什麼,用來做什麼的)Quick Start
主要包括兩部分內容:簡易的安裝部署說明(Deployment)和使用案例(Example)。Documentation
部分是核心的文件,對於大型專案可以使用超連結代替
參考:
https://gitlab.corp.realibox.com/shienming/readme-template
使用 Description Template
使用 merge request template
(待補充:https://docs.gitlab.com/ee/user/project/description_templates.html)
https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Security Release.md
版本管理規範
專案程式碼release包括三類:
- 大版本(x.0.0)
- 小版本(x.x.0)
- 補丁(x.x.x)
版本管理
git 流程模式有兩種:一種是Git flow
工作流,一種是Github flow
工作流。
Git Flow 分支模型
步驟
- master分支不做程式碼提交,master為生產環境執行程式碼
- 開發主要在develop分支上進行提交
- 功能開發切換一個新的功能分支上,功能分支完成後需合併到develop分支
- 用release分支做版本釋出,release用於預釋出環境測試
- release分支從開發分支切出來,完成後需要合併到master分支和develop分支
- 預釋出環境測試無誤後,release分支合併到master分支,釋出到生產環境測試
- 生產環境測試完成後release分支可以刪除
- 生產環境執行中緊急修復採用hotfix分支,hotfix分支從mater分支切出
- hotfix分支修復後需合併會master分支和develop分支
功能開發
建立功能分支
# 從develop建立功能分支
$ git checkout -b myfeature develop
完成功能分支,合併develop,並推送到遠端倉庫
# 切換到develop分支
$ git checkout develop
# develop分支合併功能分支
$ git merge --no-ff myfeature
# 刪除功能分支
$ git branch -d myfeature
# 推到遠端倉庫
$ git push origin develop
版本釋出
版本釋出前,建立版本分支
# 從develop分支切到版本釋出分支
$ git checkout -b release-1.2 develop
完成版本測試後,合併到master分支上
# 切換到master
$ git checkout master
# master合併release分支
$ git merge --no-ff release-1.2
# 給master分支打tag
$ git tag -a 1.2
生產環境測試沒有問題後,將release分支合併會develop分支,並刪除release分支
# 切換到develop分支
$ git checkout develop
# develop分支合併release分支
$ git merge --no-ff release-1.2
# 刪除release分支
$ git branch -d release-1.2
臨時補丁
生產環境上發現bug,直接通過hotfix快速修復:
# 從master切出一條分支,緊急修復問題
$ git checkout -b hotfix-1.2 master
完成問題修復後,合併進master:
# 切到master分支
$ git checkout master
# master分支合併hotfix分支
$ git merge --no-ff hotfix-1.2
# 打上新tag
$ git tag -a 1.2
# 切換到develop分支
如果當前release分支還未刪除,合併到release分支,再由release分支合併到develop分支:
$ git checkout release-1.2
# release-1.2合併hotfix分支
$ git merge --no-ff hotfix-1.2
# 刪除hotfix分支
$ git branch -d hotfix-1.2
# 切換到develop分支
$ git checkout develop
# develop分支合併release分支
$ git merge --no-ff release-1.2
如果release分支已刪除,則直接合併到develop分支:
# 切換到develop分支
$ git checkout develop
# develop分支合併release分支
$ git merge --no-ff hotfix-1.2
# 刪除hotfix分支
$ git branch -d hotfix-1.2
原則
- 開發永遠不直接提交到master分支,master保留用於釋出到生產中的程式碼
- 儘量一個任務,一個功能分支
- 在合併到開發分支前,對每個merge requests測試
- 新功能只新增到develop分支
優缺點
優點:
- 流程清晰,覆蓋面全,通過分支模型將工作流串通
- git flow作為最早提出的分支模型,也是最廣泛使用的分支模型,受眾廣泛
- 以master作為生產分支,面向單版本的線上產品迭代
缺點:
- 分支十分複雜,敏捷性較差
- 僅master分支上做持續整合,而大部分工具預設將master分支設為預設分支,因此經常面臨分支切換,導致很繁瑣
- 修補分支和釋出分支設定繁瑣,比如每次使用修補分支都需要同時合併到master和develop分支,但開發經常犯錯誤,比如忘記合併回develop分支
Github Flow 分支模型
面對git flow的繁瑣,github flow分支模型僅具有功能分支和主分支,將所有內容合併到master分支中並進行部署,採用pull request方式進行程式碼合併,強調持續整合和連續交付。
優點:
- 流程十分簡單,可以滿足敏捷交付
- 不需要頻繁切換分支,在自己的倉庫進行開發,統一合併master
- 每次提交均需要測試
缺點:
- 對自動化測試要求較高,需要大量的單元測、端到端測試和整合測試
- 模型過於簡單,對於部署、發版和整合上存在著大量問題
Gitlab Flow 分支模型
結合了git flow分支模型和github flow分支模型:
步驟
- 需要一個staging環境和pre-production環境(兩個生產環境映象)
- 從主倉庫 fork 到自己的倉庫
- 所有請求直接提交到master分支,每次提交都做持續整合和測試,主要是自動化測試
- 每個merge requests需要描述符合提交規範,每個人出了程式碼輸出工作,需要每天抽出時間進行code review。
- 部署釋出的時候,從master中摘取(cherry Pick)核心釋出功能到"release-x.x.x-alpha"分支進行測試,並在其上進行修復
- 測試通過後,切換到"release-x.x.x"分支並刪除"release-x.x.x-alpha"分支,將"release-x.x.x"分支釋出到生產環境中進行測試
- 生產環境測試通過後,將"release-x.x.x"合併回master
要使用好cherry-pick,每個提交要清晰簡潔
功能開發
# fork到使用者倉庫
# 拉取到本地修改
$ git clone <your repo>
# 切出一個分支
$ git branch -b feature/xx
# 提交
$ git commit
# 上傳到自己的倉庫
$ git push origin
# 向主倉庫發起merge requests請求,合併到主倉庫master
# CI通過並且其他人code review後同意即可合併到主倉庫
預釋出
# 從最新的release版本切出一個新的版本分支release-x.x.x-alpha
$ git checkout -b release-x.x.x-alpha
# 從master分支cherry-pick所需提交記錄
$ git cherry-pick hash1 hash2 hash3
# 上傳到自己的倉庫
$ git push origin
# 向主倉庫發起merge requests請求,合併到release-x.x.x-alpha
# CI通過並且其他人code review後同意即可合併到主倉庫
優缺點
優點:
- 相比git flow分支模型更簡單,減少了分支數量
- 和github flow分支模型一樣,更強調測試,對所有提交都需進行測試或code review
缺點:
- 需要自動化測試流程支撐,需要有較好的持續整合和連續交付基礎
commit規範
git commit 提交樣式規範:
<型別>: <標題>
<空一行>
<內容>
<空一行>
<結尾>
<型別>
用於說明 commit 的類別,只允許使用下面7個標識。
- feat:新功能(feature)
- fix:修補bug
- docs:文件(documentation)
- style: 格式(不影響程式碼執行的變動)
- refactor:重構(即不是新增功能,也不是修改bug的程式碼變動)
- test:測試相關改動
- chore:構建過程(CI/CD)或輔助工具的變動
<題目>
commit 目的的簡短描述,不超過50個字元
<內容>
對本次 commit 的詳細描述,可以分成多行,可詳細說明程式碼變動的動機
<結尾>
Footer 部分只用於以下兩種情況:
不相容變動
如果當前程式碼與上一個版本不相容,則 Footer 部分以BREAKING CHANGE開頭,後面是對變動的描述、以及變動理由和遷移方法。
BREAKING CHANGE: isolate scope bindings definition has changed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
}
After:
scope: {
myAttr: '@',
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
關閉 Issue
如果當前 commit 針對某個issue,那麼可以在 Footer 部分關閉這個 issue 。
Closes #234
Example
feat(compiler): comments for if-else conditions #10286
In order to fix these 2 issues, I need to have access to the HTML comments before a v-else block
vue-styleguidist/vue-styleguidist#430
vue-styleguidist/vue-styleguidist#322
To give you an example, here is a format that does not work with the current parser.
Since we cannot have the comments as normal nodes, I thought we could have the missing comment beside the ifCondition.
closes #10288
Revert
還有一種特殊情況,如果當前 commit 用於撤銷以前的 commit,則必須以revert:開頭,後面跟著被撤銷 Commit 的 Header。
revert: feat(pencil): add 'graphiteWidth' option
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
Body部分的格式是固定的,必須寫成This reverts commit <hash>
.,其中的hash是被撤銷 commit 的 SHA 識別符號。
如果當前 commit 與被撤銷的 commit,在同一個釋出(release)裡面,那麼它們都不會出現在 Change log 裡面。如果兩者在不同的釋出,那麼當前 commit,會出現在 Change log 的Reverts小標題下面。
Commitizen
可以使用典型的git工作流程或通過使用CLI嚮導Commitizen來新增提交訊息格式。
安裝
npm install -g commitizen
然後,在專案目錄裡,執行下面的命令,使其支援 Angular 的 Commit message 格式。
commitizen init cz-conventional-changelog --save --save-exact
以後,凡是用到git commit
命令,一律改為使用git cz
。這時,就會出現選項,用來生成符合格式的 Commit message。
生成 Change log
如果你的所有 Commit 都符合 Angular 格式,那麼釋出新版本時, Change log 就可以用指令碼自動生成。生成的文件包括以下三個部分:
- New features
- Bug fixes
- Breaking changes.
每個部分都會羅列相關的 commit ,並且有指向這些 commit 的連結。當然,生成的文件允許手動修改,所以釋出前,你還可以新增其他內容。
conventional-changelog 就是生成 Change log 的工具,執行下面的命令即可。
$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w
整理自CTO-石老大