Alan Tsai 的學習筆記


學而不思則罔,思而不學則殆,不思不學則“網貸” 記錄軟體開發的點點滴滴 著重於微軟技術、網頁開發、DevOps、C#, Asp .net Mvc、Azure、AI、Chatbot、Docker、Data Science

[Azure DevOps]如何設定Pull Request的預設文字模板(template)

2019-03-21 星期四
[Azure DevOps]如何設定Pull Request的預設文字模板(template).jpg
圖片來源:https://pixabay.com/en/despair-alone-being-alone-archetype-513528/

Pull Request是一個非常好的Code Review方式,也是當初Github讓git火紅起來的其中一個原因之一。

在建立Pull Request的時候,一般會有一段訊息可以輸入,這個訊息主要描述了這一次Pull Request的一個主要目的。

但是,當團隊合作開發的時候,很有可能A工程師會輸入一種格式的内容,而B工程師又是另外一種。或者有時候有些條件需要符合才應該發起Pull Request,但是工程師忘記了,造成Reviewer需要花時間最後才發現根本最基本的條件都沒達到。

有沒有什麽方式可以提醒工程師在Pull Request發起的訊息要打好,並且該檢查的東西都要檢查過了呢?

這一篇,來看看在Azure DevOps裡面,如何透過建立template(範本)達到這個需求。

爲什麽需要自訂Template

從開頭大概知道了爲什麽應該要自訂template,快速總結一下。

自訂template的好處有:

  1. 可以確保建立Pull Request的人知道應該至少要輸入什麽
  2. 可以作爲一個checklist,提醒某些事情要做好在開pull request
  3. Pull Request輸入的文字會變成commit message的一部分 - 在未來查找歷史很有幫助

光列出優點可能沒什麽感覺,直接看一個對比差異就有feel了。

首先,如果是一個沒有template的情況,那麽預設的Description呈現的是commit的訊息,例如:

chrome_2019-03-21_08-06-55.png
預設的畫面

好吧,這個demo的commit訊息爛了一點,但是正式情況可別這樣

相較而言,如果今天有個template看到的可能是:

chrome_2019-03-21_08-11-48.png
有template的情況

有template在搭配markdown裡面的checkbox,可以很容易建立出一個checklist,可以讓建立的人,做好每一項的時候把已經做好的打勾,然後reviewer只需要一看有沒打勾的直接退回,節省時間。

如果説今天只是用Azure DevOps做版控,但是issue tracking在別的地方,那麽這個時候就沒辦法用work items直接關聯,但是就可以用第三項的形式把對應issue貼上。

有個好處是,當pull request完成的時候,這邊的訊息會一起進入commit message,未來很好查log的時候找到原始的單。

有feel了之後就要看看如何建立。

如何建立自己的template

要建立template非常的簡單,需要瞭解兩個概念:

  1. Template要放在某個特殊位置
  2. Template名稱+位置可以決定什麽時候自動出現

Template要放在某個特殊位置

Template是放在 Git Repo裡面,換句話説,和Source Code放在一起。

不過放在那邊是有特殊位置,總共有:

  1. 放在root下面的.azuredevops資料夾裡面
  2. 放在root下面的.vsts資料夾裡面
  3. 放在root下面的docs資料夾裡面
  4. 放在root下面

以上幾個路徑是接下來這篇文章提到的所有的base,因此後面提到建立資料夾等都是建立在上面提到的幾個路徑之下。
由於Template是和source code一起的,那麽哪一個branch的template會啟作用?Default Branch的會啟作用,後面會詳細介紹。

放那邊就看各人的喜好啦,我喜歡放在docs下面,因爲我個人建議所有的專案建立的資料夾結構就有docs

置入一下以前的另外一篇文章:該怎麼開專案的資料夾結構?每個專案應該要有的資料夾結構和檔案

有了位置,接下來就是要看Template名稱和位置的差異。

Template名稱和位置可以決定什麽時候自動出現

知道了基本路徑之後,就需要瞭解一下template的名稱以及會影響到的出現時間。

總共有3種類型的template:

  1. Default Template:如果其他都沒有的情況下,要使用的Template
  2. Branch Template:要指定pull request的目標是某一個branch的時候用
  3. Additional Template:這種template不會預設使用,而是放在旁邊可以讓建立Pull Request的人選用

知道了不同差異,來看看每一個如何設定以及使用

Default Template

只需要在上面提到的base資料夾下面加入一個檔案名稱為:

  1. pull_request_template.md
  2. pull_request_template.txt
兩個二擇一即可。其實就是以md結尾或者txt結尾的一個pull_request_template檔案。

所以以下範例位置都有一樣的效果 (完整的路徑):

  • {repository root}/.azuredevops/pull_request_template.md
  • {repository root}/.vsts/pull_request_template.md
  • {repository root}/docs/pull_request_template.md
  • {repository root}/pull_request_template.md

Branch Template

有時候不同的branch要有不同的注意事項,這個時候就可以用branch template來蓋掉default template

只需要在上面提到的base資料夾下面的pull_request_template/branches/,然後branch名稱為檔案名稱結尾是md或者txt

舉例來説,如果今天有個針對merge到master branch的template,那麽下面擇一即可(完整路徑):

  • {repository root}/.azuredevops/pull_request_template/branches/master.md
  • {repository root}/.vsts/pull_request_template/branches/master.md
  • {repository root}/docs/pull_request_template/branches/master.md
  • {repository root}/pull_request_template/branches/master.md

target branch名稱會match到 {branch}/*。換句話説,如果有個branch template是feature.md,那麽 feature,或者feature/*都會使用這個
chrome_2019-03-21_20-08-35.png
如果有設定master branch template,那麽他會變成預設

Additional Template

有些Template預設不會使用,但是如果要用的話可以容易加入,這種就是Additional Template。

建立很簡單,只需要在上面提到的base資料夾下面的pull_request_template/,然後任何檔案名稱結尾是md或者txt

舉例來説,如果今天有個Additional Template叫做Addition,那麽下面擇一即可(完整路徑):

  • {repository root}/.azuredevops/pull_request_template/addition.md
  • {repository root}/.vsts/pull_request_template/addition.md
  • {repository root}/docs/pull_request_template/addition.md
  • {repository root}/pull_request_template/addition.md

下圖左邊可以看到總共有3種template,然後可以透過點選説明游俠框的地方去選擇要不要使用template:

chrome_2019-03-21_20-10-40.png
檔案結構並且如何apply template

常見問題 - 爲什麽template沒有出現

當遇到template有設定,但是沒有出現的時候,注意兩件事情:

  1. 確認template放在正確位置以及檔名格式是正確
  2. 確認template放在了Default Branch裡面

第一點檢查沒什麽好説,就看上一段的内容,看要什麽template,就檢查那個。

但是第二點的Default Branch是什麽?

在Azure DevOps有所謂的Default Branch,也就是預設要做pull request的時候選擇的branch。Template要放在這個branch裡面才有作用。

在Azure DevOps切換到Branch就可以看到那個是default,預設都是master
chrome_2019-03-21_20-16-27.png
預設branch會有一個tag在旁邊寫Default

知道了怎麽看Default Branch之後,下一個問題就是怎麽改?

修改只需要:

  1. 點選選左下角的Project Settings
  2. 選擇Repositories
  3. 展開repo,然後找到要設定為Default的那個branch
  4. 點選旁邊的3個點,就會出現選項:Set as default branch

chrome_2019-03-21_20-18-25.png
修改Default Branch的方式

結語

我們常説,刪比新增來的快,因此有個template除了可以提醒要做什麽之外,如果有一些常見的輸入内容也可以用template幫大家準備好,只需要套用然後微調就好。

或許看起來只是小地方,但是可以讓未來維護或查找變得更加方便。

參考資料

官方的説明文件
Improve pull request descriptions using templates

如果文章對您有幫助,就請我喝杯飲料吧
街口支付QR Code
街口支付QR Code
街口支付QR Code
支付寶QR Code
街口支付QR Code
微信支付QR Code
2019-03-21 星期四
comments powered by Disqus