代碼倉庫建立規範

代碼倉庫建立規範

一、 項目建立需符合Group規範。html

二、 建立項目必須添加Project description說明。vue

三、 每一個項目都須要README.md文件。node

四、 除文檔說明類型倉庫,全部代碼倉庫都須要.gitignoregit

注:有模板的項目,要以統一的模板建立項目github

Groups使用規範

Group 分爲 rule(技術行爲規範)、lab(技術預研)、common(基礎庫)、realicloud(基礎平臺)、rexxox(產品)、customer(定製化開發項目)
算法

目錄結構及權限介紹

  • rule - Internalnpm

    • 主要用於存放技術行爲規範相關資料
  • lab - Internal小程序

    • 主要用於存放技術預研,好比shader預研、售前demo技術預研等。
  • common - Internalide

    • 主要用於存放公共組件庫,基礎算法庫
  • 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 部分是核心的文檔,對於大型項目可使用超連接代替

參考:

使用 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 分支模型

img

步驟

  • 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分支模型:

img

步驟

  • 須要一個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-石老大

相關文章
相關標籤/搜索