Alan Tsai 的學習筆記


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

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

2019-03-21 Thursday
[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
台灣 Pay QR Code
台灣 Pay QR Code
Line Pay 一卡通 QR Code
Line Pay 一卡通 QR Code
街口支付QR Code
支付寶QR Code
街口支付QR Code
微信支付QR Code
2019-03-21 Thursday
comments powered by Disqus