MUKI AI Summary
公司專案從 GitLab 轉移到 GitHub，為了團隊協作更順利，建立了 PR 和 issue template。PR template 放在 .github 資料夾，檔名為 PULL_REQUEST_TEMPLATE.md。issue template 有 markdown 和 yml 兩種格式，yml 支援表單元件，推薦使用 yml。建立多個 issue template 時，資料夾命名為 ISSUE_TEMPLATE，並建立 config.yml 檔案。所有更改需推到預設 branch 才能自動載入 template。...
前言
我自己在發 PR 或 寫 issue 時，會希望能使用固定的發文格式，因為透過統一的文章格式，能有利於團隊協作，也能讓畫面更整齊美觀 XD。
而近期公司專案從 GitLab 轉移到 GitHub，我們的測試和 PM 也加入了我們一起使用 Git，所以除了 PR template 外，我也建立了 issue template，希望能讓團隊協作更加順利。
撰寫 PR template
跟 如何使用 GitHub 的 Actions 自動產生 Release 文件 一樣，我們要將 template 放在 .github 資料夾底下。
PR template 只會有一個檔案，檔名也是固定為 PULL_REQUEST_TEMPLATE.md，請不要隨意修改唷。
▼ 這份是我幫團隊建立的 PR template，有需要的朋友歡迎直接複製修改。如果有更好的寫法，也歡迎分享給我 ^Q^
## 描述 **將這支 PR 所做的事情，取代這段文字，描述越詳細越好。** 相關的 issue #(ticket number) / 無 ## 變更的類型 - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] This change requires a documentation update ## 影響的頁面 - [] 首頁 - [] 個人資料與設定 - [] 其他（請填寫） ## 相關的 專案網站(ex.Redmine) Task (如果有相關的 task，請填寫連結，如果沒有請刪除此行，並填「無」) ## 檢查清單 - [] 我已經在本地手動測試過，確保功能的完整性和穩定性 - [] 我對我的程式碼進行了註解，特別是在難以理解的地方 - [] 我已經更新了文件，或者我的更改不需要更新文件 - [] 我的 PR 有明確的標題與內容描述
▼ 存檔後 push 到你的專案並 merge 到 main branch，每次發 PR 時就會自動載入這個 template 了。
撰寫 Issue template
Issue 的 template 有兩種格式，一種是用 markdown(.md)，一種是 yml(.yml)
markdown 就是跟 PR template 一樣，會有一個框框裡面有預設的資料。
而 yml 是 GitHub 官方主推的寫法，可以有如 input，textarea，dropdown，checkbox... 等等表單元件，能直接做一個完整的表單
▼ 使用 yml template 的話，新增 issue 時可以選擇想要的 template
▼ 然後就能愉快的一個蘿蔔一個坑，填入對應的表單內容。也能自動設定好 Label
我原本是想用 markdown，但看了 yml 的範例語法後，發現沒想像中的不複雜，所以就改用 yml 了。因此這篇文章會介紹 yml 唷。
▼ 如果你跟我一樣，想要建立多個 issue template，那你的資料夾結構會長得像這樣
請在 .github 裡面建立一個資料夾，資料夾名稱為 ISSUE_TEMPLATE(不可修改)
再建一個 config.yml (同樣不可修改)
剩下的 enhancement.yml 以及 fix.yml，就是我們對應的 issue template，這裡就能依照自己的喜好修改檔名囉。
關於 config.yml
▼ 這是我的 config.yml 內容，如果使用多個 issue template，這邊通常只會有這個設定值，如果想要更多設定，可以參考 GitHub 的官方文件
blank_issues_enabled: false
blank_issues_enabled 的意思是，使用者新增 issue 時，能不能不用我們寫好的 template，而是用自由書寫的格式？
你可以根據自己的喜好調整，true 是開放；false 為不開放，亦即只能用你設定的格式寫 issue。
關於 issue template
這邊以 fix.yml 為例，跟大家分享我的 template，也歡迎自行複製修改
name: Bug 回報
description: 提交一個錯誤 / 問題
title: "[BUG] 標題"
labels: ["type: bug(fix)"]
body:
- type: checkboxes
attributes:
label: 是否已存在相關的問題？(必填)
description: 請搜尋看看是否已有類似的錯誤問題。
options:
- label: 我已搜尋過現有的問題
required: true
- type: input
attributes:
label: 發生時間(必填)
description: 格式 YYYY-MM-DD HH:MM
validations:
required: true
- type: textarea
attributes:
label: 當前行為(必填)
description: 簡單描述做了什麼事情
render: markdown
validations:
required: true
- type: textarea
attributes:
label: 預期行為
description: 簡單描述原本預期會發生什麼事情
render: markdown
validations:
required: false
- type: input
attributes:
label: 網站版本號
description: 位於網站下方
validations:
required: false
- type: textarea
attributes:
label: 平台環境
description: |
例:
- **作業系統**: Ubuntu 20.04
- **瀏覽器**: Chrome
- **瀏覽器版本**: 13.14.0
value: |
- 作業系統:
- 瀏覽器:
- 瀏覽器版本:
render: markdown
validations:
required: false
- type: input
attributes:
label: 網站錯誤碼
validations:
required: false
- type: textarea
attributes:
label: 其他補充
description: |
任何連結、截圖或影片等補充訊息，都可以寫在這裡。
提示：可以點擊此區域以突出顯示，然後拖入圖片或相關文件。
validations:
required: false- yml 格式最注重的是階層，因此要特別注意縮排，不要跑掉了唷。
- yml 相關的 type 以及可用的 attributes，可參考 Syntax for GitHub's form schema
- 檔案第四行的
labels: ["type: bug(fix)"]要改為你自己想要設定的 issue Label，因為是陣列格式，所以可以為複數。 - 如果你使用的是組織的 git，那表單的 required: true 是沒有作用的，也就是說即使設定了必填欄位也也是無效的，我有翻了一下相關 issue，目前仍沒有解決，可參考 #43859， #45084，#51500
最後記得，所有的更改都必須要推到你的預設 branch (通常是 main) 才能自動載入 template。
結語
Happy Coding !!
4