但這時會遇到一個問題：「每個人對專案的認知有差異，且文字表達能力不同。」

這會導致 Code Review 的人需要花更多的時間來理解程式，甚至浪費寶貴的時間在溝通上；有些交代不清楚的 Merge Request 如果被合併了，也容易在未來發現 Bug 時難以釐清問題。

而解決上面問題的方式也很簡單：「建立 Template（模板）」

如果大家都按照模板撰寫，就能保證每個 MR 都有一定的品質。

Merge Request 要有哪些資訊？

筆者個人建議一個好的 Merge Request 要包含以下元素：

1. 概要 & 背景：簡短描述這次 Merge Request 的目的，讓 Code Review 的人可以快速理解前因後果。
2. 相關資訊：放上專案需求規格連結、關聯的 Project/branch、會議紀錄等資訊。
3. 變更內容：說明新增/修改/移除了什麼內容，如果邏輯複雜可以簡述演算法。
4. 測試步驟：描述如何驗證這次的變更，包括需要運行的測試和預期結果。

大家可以參考我的 Merge Request Template 格式（Markdown 語法）：

# 概要 & 背景

# 相關資訊

- 需求規格: 
- 關聯的 Project/branch: 
- 任務 Ticket/會議紀錄: 

# 變更內容

- [新增] xxx
- [修改] yyy
- [移除] zzz

# 測試步驟

### 測試項目 1

- STEP 1: 
- STEP 2: 
- STEP 3: 

預期結果:

英文版：

# Summary & Background

# Relevant Information

- Requirement Specifications: 
- Associated Project/Branch: 
- Task Ticket/Meeting Notes: 

# Changes

- [Added] xxx
- [Modified] yyy
- [Removed] zzz

# Testing Steps

### Test Case 1

- STEP 1: 
- STEP 2: 
- STEP 3: 

Expected Result:

在 Gitlab 建立 Merge Request Templates 的步驟

STEP 1: 選擇 Project default branch，建立存放 Templates 的資料夾

我們要先在根目錄下建立 .gitlab/merge_request_templates/ 的資料夾。

小提醒：一定要在「default branch（ex: main、develop）」下建立，否則是沒有效的。

STEP 2: 在資料夾下建立「.md」的 Templates

你可以直接複製筆者在前面提供的 Markdown Template，這邊我將檔案命名為「merge.md」。

這邊我開一個測試的 branch 來做 Merge request，大家可以看到在 Description 旁邊有一個下拉選單，裡面的 merge 就是我們剛剛新增的模板。

選擇後就能看到剛剛建立的 Merge request Template：

相信一個好的 Merge request Template 能提高專案的品質，並加速團隊的協作流程，減少不必要的溝通成本。

軟體工程 Edit description dean-lin.medium.com

由於過去許多工作流程都是口頭制定，沒有明確的文字敘述，因此想透過這篇文章來整理流程，並在日後的實踐中不斷優化與完善。

大綱
ㄧ、專案初始
二、初始任務
 ➤ 評估每個階段的時程
 ➤ 撰寫 Ticket 的需求規格
 ➤ 估計每個 Ticket 的時數
 ➤ 確認 Ticket 的總時數是否在專案的截止日期內
 ➤ Ticket 分配
 ➤ 專案初始環境建置
 ➤ Server 建置
三、專案進行中
 ➤ 進度回報
 ➤ 工程師之間的合作
 ➤ 工程師與 PM 的合作
 ➤ 了解為什麼都要由 PM 來開 Ticket

ㄧ、專案初始

STEP 1：由 PM 與客戶討論具體需求。

STEP 2：請 UI/UX 設計師依造需求初步完成 Wireframe。

STEP 3：PM、UI/UX、Tech Lead 一起確認流程、功能的可行性，判斷是否有需要調整的部分。

STEP 4：待客戶認可 Wireframe 後，請 UI/UX 設計師將其升級成 Mockup。

STEP 5：由 Tech Lead 確認 Mockup 上需要注意的細節（ex：哪些欄位適合拿來搜尋、不同權限看到的畫面、有哪些元件可以設計為共用模組）。

STEP 6：在 UI/UX 設計師調整為 Prototype 後，由 PM（或 UI/UX 設計師）向團隊成員說明系統的功能與流程，確保大家理解這個專案要完成的目標。

STEP 7：由 Tech Lead 向工程師團隊說明各功能在設計上要注意的細節（ex：哪些欄位要設計 Auto-Complete、是否有特別的 Validation Rules、某些功能需要提前 Survey 避免卡關）。

良心建議：專案初始的設計盡量從 Wireframe 開始，就算專案規模較小也不要直接畫 Mockup；因為客戶的需求在前期會時常變動，就算突然加大投資，小專案突然變成大專案也是很常見的，若使用 Mockup 會要花更多的時間在調整上面。

二、初始任務

評估每個階段的時程

由 PM 將專案的需求拆分成不同的 Phase，這樣工程師比較能集中注意力在特定事物上，每個 Phase 都需要把如下的任務納入考量：

1. 要完成的功能（ex：前端、後端）
2. 撰寫測試程式的時程（ex：單元測試、壓力測試）
3. QA 團隊測試的時程
4. 測試、正式環境部署的時程

規劃時要保留「緩衝時間」，因為測試一次就過基本上是不可能發生的事情，往往需要預留 15~30% 的時間來修 Bug。

撰寫 Ticket 的需求規格

由 PM 在專案管理系統上為每項任務建立 Ticket，建議需求規格的內容要包含：

1. Prototype 截圖：讓工程師明白功能具體的位置在哪。
2. 需求描述：說明這個功能是用來做什麼的，它跟哪些功能有相依性。
3. 相關計算規則：以計算商品總價來說，就會有「產品搭配、折價卷、信用卡優惠…」等多種排列組合。
4. 使用的邏輯：搜尋欄位可以查詢的欄位有哪些？搜尋的邏輯是 And 還是 Or？
5. 關聯需求：像是後端做完 API 後交付給前端，就需要將兩個 Ticket 關聯。

估計每個 Ticket 的時數

不同 Ticket 的難易度不同，這邊會由 Tech Lead 分別向 Frontend、Backend 工程師確認 Ticket 的估時。

此時工程師千萬不要勉強自己，估出一個很難完成的時數，不然在卡關時，會影響到後續一系列的時程規劃。（但也不要估出不合理的時數）

如果某個 Task 預估的時程超過 6 小時，建議要再做細分，否則很難衡量每天實作的進度。

確認 Ticket 的總時數是否在專案的截止日期內

只要是專案就一定有截止日期，如果將每個預估的時數加總後，發現已經超過了專案的截止日期，那勢必要做一些調整，比如：

1. 簡化部分功能（ex：原本要用 Auto-Complete，現在改用一般的搜尋）。
2. 規劃 MVP 先交出去讓客戶使用（ex：原本要經過一系列複雜的流程才能建立的資料，先用 Seeder 代替，以此大幅減少工程師的開發時程）。

這邊不建議堅持原計劃完成所有功能，因為快速開發所累積的技術債，於未來要花更多的時間處理。

Ticket 分配

由 PM 規劃在這個 Sprint 中要完成的 Ticket，然後在 Sprint Planning 時進行細節分工；假設一個 Sprint 為 2 週，建議每個人身上掛的 Task 時數不要超過 60 小時，因為：

1. 時常會有臨時的會議、需求、Bug…等意外事件，需要保留緩衝時間。
2. 在專案的初始階段，我們無法保證是否由遺漏的規劃、邏輯的錯誤，若把時間塞滿就很難有轉圜的餘地。
3. 舊的維護專案，有時會有緊急的狀況需要優先處理，這也會吃掉不少時間。

專案初始環境建置

由 Tech Lead 或是 Senior Engineer 負責專案初始環境建置，初始化的專案需要在 README.md 中有以下說明：

1. 環境需求：Node.js 版本、PHP 版本、MySQL 版本…
2. 如何在 Local 端建立：安裝流程、環境變數…

Server 建置

由 Tech Lead 開出專案系統所需的硬體配置（正式機、測試機）、DNS、要安裝的軟體/套件（ex：Ubuntu Server、MySQL、Node.js、PHP…各自的版本），並請 PM 填寫需求單讓 MIS 依照此規格進行建置。

三、專案進行中

進度回報

如果團隊有使用專案管理系統，為了日後方便追朔與釐清狀況，建議填寫的內容如下：

1. 如果實作的方向是討論出來的，請紀錄「與會人員」與「決議結果」。
2. 如果使用到特別的演算法、技術、套件，請特別附註。
3. 如果該 Ticket 完成後要由其他人接手處理（ex：後端完成 API 後交付給前端），請說明要執行哪些指令（ex：DB Migration、Seeder…），並提供相關的 API 文件。
4. 如果發現該 Ticket 完成所花時間與當初的估計有所不同，請與 PM 討論並調整。

工程師之間的合作

1. Ticket 執行順序：一個 Sprint 中，每個工程師都會有很多的 Ticket，但有些 Ticket 會有所謂的「前置條件」，建議在開始作業前要先彼此商議，避免出現等待的空窗期。
2. 回報 API Bug：請說明是在「哪個系統」、「哪隻 API」、「什麼參數下」會發生。
3. 回報 Web Bug：請說明是在「哪個系統」、「哪個畫面（截圖）」、「什麼操作下」會發生。
4. 遇到自己無法解決的問題：請說明是在「哪個系統」、「哪個 Ticket」、「你做過哪些嘗試」、「你認為可能的解決方案」。

工程師與 PM 的合作

1. PM 請工程師完成 Sprint 以外的需求時，請說明「任務優先度」、「為什麼會有這個需求」、「可以先將哪個 Ticket 排後面一點」。
2. 如果工程師在開發過程中收到其他團隊的需求，請將對話窗口轉移到 PM。
3. 如果工程師要請 PM 協助開 Ticket，需描述：「哪個系統」、「要處理的任務/Bug」、「預計要做的事項」、「預計完成所需時間」。
4. 若身上的 Ticket 數量爆炸多、任務分配不均，請及時反應。

如果是同一個專案，我們可以輕鬆的排出任務的優先順序；但如果多個專案同時發起優先度高的任務，工程師在這種狀況下會不知所措，需要由 PM 協助排出優先順序。

了解為什麼都要由 PM 來開 Ticket

1. 如果大家都自己開 Ticket，PM 會無法掌握每個人實際在做的任務，即使有 Tag 到 PM，PM 也未必有辦法看到每一則訊息。
2. 工程師心中的任務優先順序可能與 PM 不同，這會造成最後在核對完成的任務時，因為彼此的認知落差產生爭執。
3. 每個任務完成所需的時間成本不同，可能有些任務是可以不必做，又或者是能交給其他人去做的，讓 PM 從整體的角度去看較不會出現勞逸不均的狀況。

制定大家願意共同遵守的工作流程，在了解彼此的權利＆義務後，相信團隊的運作會更為順利；文章的流程未必適用於每個團隊，僅為筆者過去經驗的彙整。

工程師血淚史
▋ 團隊在系統開發上遇到了哪些問題
▋ 需求不斷變更，到底哪個環節出錯了
▋ 當 Scrum Master 跟 PM 同時存在，權力與責任該如何區分？
▋ 如果沒有明確的開發流程，團隊將會無所適從(本篇)
▋ 你知道對專案來說，README.md 有多麼重要嗎？

大綱
➤ 可以一起遵守的 Coding Style
➤ 使用相同的程式碼 Format 工具
➤ 沒有明確 Git Flow 機制會發生什麼事？
➤ 制定團隊 Git Flow 的規則

可以一起遵守的 Coding Style

即使是有經驗的工程師，在同一個專案中也很常不小心有多種命名的風格，下面列出幾個建議：

• 變數與函式：都用小駝峰式（camelCase）的命名，ex：downloadDoc、deleteDoc。
• 常數命名：會建議使用全大寫英文命名，字詞間使用下底線（_）連接，ex：VUE_APP_ROOT_API。
• 少用簡寫或自己發明縮寫：就算是本人，幾個月後也會忘記自己當時創造的東西。
• 不要拼錯英文單字：當程式結構越來越大，我們會透過搜尋來找答案，如果你拼錯就會造成大家的困惑。
• 字串單引號、雙引號統一：儘管在 JavaScript 中兩者皆可運行，但在閱讀體驗上就會有點不舒服。

使用相同的程式碼 Format 工具

其實上面的問題大部分可以透過「工具」來解決，但必須律定團隊使用「統一」的工具。

如果團隊沒有統一的工具，會導致你每次在更新專案時，明明只更新一行，但因為每個人 Format 工具不同導致在 Merge Branch 時看起來幾乎是重寫。

這邊推薦使用 VSCode Extensions 的 Prettier，他支援大部分程式語言的 Format；當然知名的 ESLint 也是團隊協作時的好選擇。

不同 Format 工具的斷行字數、單引號、雙引號、結尾有沒有「;」…的習慣都不一樣，如果大家不統一，你看 diff 時會覺得很崩潰並且浪費時間。

沒有明確 Git Flow 機制會發生什麼事？

如果沒有一套基礎簡單的規則，你可能會遇到以下障礙：

• Deploy（部署）沒有基準：正式機、測試機要用哪個 Branch？如果每次都不一樣，那遲早都會出事。
• 花很多時間在 Merge Branch（合併分支）上：如果不是從同一條 Branch 分支出去，那在 Merge 時很容易出現各種衝突需要解決。
• 難以從 Branch 追蹤作業進度：有些人會只用一條 Branch 從頭做到尾，造成單純看這個分支無法理解他到底完成了哪些功能。
• 無法理解的 commit 內容：每個人都有自己的 commit 風格，導致追溯歷史時很難找到節點。
• 任務交接時的困擾：有些人沒有定期 push 的習慣，喜歡累積非常多的 commit 再一次 push；這樣如果他突然請假，或剛好在忙其他事情時，職務代理人並無法協助處理他的任務，甚至重工浪費時間。

制定團隊 Git Flow 的規則

下面是筆者團隊在各個 Branch 的規則：

🏷️ Master

• 功能：部署到正式機的 branch
• Merge request：由資深工程師或是技術主管審核

🏷️ Develop

• 功能：部署到測試機的 branch
• Merge request：由資深工程師或是技術主管審核

🏷️ Feature

• 命名方式：依功能命名，如果有任務編號的話一同附上，方便日後追蹤
• 基礎規則：原則上都是從 Develop 分支出去，每個 Feature 的功能盡量細分到可以在一天內完成

🏷️ Hotfix

• 命名方式：依功能命名，如果有任務編號的話一同附上，方便日後追蹤
• 基礎規則：原則上是為了解決正式機上面的緊急 Bug，因此通常是從 Master 分支出去；完成修改後再合併回 Master、Develop

🏷️ Release

• 命名方式：依釋出的版本命名
• 基礎規則：當有一個大版本準備部署到正式機，為了保證系統穩定性，會先從 Develop 分支 Release 的版本

以及其他希望大家一起遵守的細節：

• 完成 Feature 時要 push 一版，並通知協作夥伴確認功能。
• 如果該 Feature branch 已經 merge 回 develop，且不會再使用該 branch，就需要把它給 delete 掉，避免線上有太多分支，會不清楚哪一個才是有在作用的。
• 每天下班前至少要 push 一版，讓管理者容易掌握進度。
• commit 可以用「新增功能、變更功能、修補 Bug」作為 title 的分類，然後將調整的內容條列式寫入 description，這樣其他人在 Code Review 時可以知道重點，範例如下：

### title
修補 Bug：解決職員列表 issues
### description
1. 解決排序無效 bug
2. 在「異常」欄位增加是否為 null 的判斷，避免字串切割異常
3. 解決 pagination 參數沒有傳送到的問題

筆者認為「簡單、易懂」為第一優先，中英文表達都可以。

相信還有很多可以讓開發團隊協作更愉快的工具與方法，期待大家的留言分享～

如果你對目前的職涯感到迷茫，想從不同視角檢視自己的選擇，相信《工程師下班有約》這本書能為你帶來靈感與啟發：

下班有約系列文
▋ [前端]新手工程師容易卡住的問題
▋ [前端＆後端]工程師常犯的錯誤
▋ 讓開發團隊更好協作的方式(本篇)
▋ 談談 Pair Programing
▋ 談談工程師的話語權
▋ 出社會後，新鮮人要及早知道的 5 件事
▋ 面試的性向測驗竟然準到讓人心裡發寒？
▋ 反其道而行的任務分配
▋ 現在的 Daily Scrum 真的適合團隊嗎？
▋ 用低成本也能請到好員工？資深 HR 不想告訴你的秘密！