#blog/ironman/draft
在前一章我們知道了哪些資訊應該在回報問題時附上，得以讓開發團隊善用該資訊儘速給予答覆或是除錯。但現實總是殘酷的，不見得所有的使用者都會知道這些要附上這些資訊，就算知道也不一定會勤於每次回報問題時都附上，講句難聽的，商業軟體有問題是開發團隊該負責的，使用者願意回報就已經是願意幫忙的，如果還要求每次都要制式風格回覆，不見得使用者都願意配合。（開源生態另當別論，開源生態是作者願意開發程式碼並開源提供給公眾使用已經仁至義盡了，並沒有義務要不斷維護。）
要讓使用者願意回報完整的資訊給開發團隊，比較直接的作法就是在填寫回報的表單裡提供完整的資訊，讓使用者能夠了解有什麼資訊是開發團隊需要的、該怎麼取得那些資訊，而避免直接丟一個空白的文字框要求使用者自己填寫，填寫後又以提供資訊不足拒絕受理。若是透過 Github、Gitlab 管理問題回報，可以透過 Issue Template 的功能去自訂問題回報時，文字框預設會出現哪些資訊，這部分將在下一章提及。另外也可以在如前面陸續有在提及的，請客服和使用者溝通，協助使用者提供該資訊，透過此方法，就是要對客服做相關知識的教育訓練。
另外，若是在自家團隊或是開源專案，頻繁遇到內部人員在回報問題時，不遵守培訓或是表單提供的格式回報問題，不應該遷就接受，而是制定一個固定的時間（例如一到三天），在這個時間沒有改善，就直接關閉、封存該回報，不予受理。在這類議題，比較常遇到的就是業務或是客服無心遵守，認為自己的描述已經夠清楚了，而不願意再多耗費時間協助提供完整的資訊。或是工程師認為自己只是先輸入個關鍵描述，之後「自己」會再處理，不用那麼繁瑣再輸入。但通常結果都是開發團隊並不了解那些不完整的資訊是在填寫什麼問題，或是最後那個異常的處理者不是回報的工程師了，導致這個回報到最後並沒有提供它該有的幫助，反而成為異常清單中想移除卻又不敢移除的臭石頭。所以，打從最初就規定沒有符合規格的異常回報不受理，對於內部團隊是一個必須的措施。別把回報時的偷懶，連本帶利的變成開發團隊要代償的債務。
在上一章有提到 Issue Template 可以協助我們自訂回報異常時的格式，本章將介紹在 GitHub、GitLab 這兩大開發者常用的交友平台程式碼託管與專案管理平台來如何善用此功能。
GitHub 文件中的 Helping people contribute to your project 有提到許多關於如何協助其他人貢獻自己專案的一些方法，其中 Creating an issue template for your repository 就有提到如何自訂 Issue Template。本節稍微摘自裡面重要的流程在此說明。
GitHub 的 Issue Template 是透過在**預設分支（defaut branch）**中，建立一個名為 issue_template.md （大小寫皆可）的檔案來設置，並可以選擇放置在可見的專案根目錄下、docs 目錄底下、或是隱藏的 .github 目錄底下。除了 md 以外，亦可以以 txt 為副檔名。
GitLab 文件中的 Description templates 有提到如何自訂 issue 和 merge request 描述的樣板。本節稍微摘自裡面重要的流程在此說明。
和 GitHub 相同，GitLab 也是透過在預設分支下建立檔案來設置 Issue Template。不同的是，GitLab 強制要求要以 Markdown 語法編寫，且必須放置在 .gitlab/issue_templates/ 目錄底下，檔案名稱即為樣板名稱，一個專案可以同時存在多種樣板，例如異常回報可以取名為 Bug.md，我們也可以針對異常的種類再去做更詳細的分類。目前 GitLab Free 方案或是 CE 版，並沒有提供設置預設樣板的功能。
在樣板的開頭，就把回報異常應注意哪些事項的說明寫上，讓回報者一定會看到這些描述也是個不錯的方式。TensorFlow 的 Issue Template 就在開頭把說明講得很清楚。
由於 Markdown 是有支援 HTML 語法的，所以理當可以使用 HTML 的註解語法。我們就可以善用這個特性，將想要對回報者說但不想在回報後顯示在頁面的話，透過註解語法包覆起來。像是：
<!--
在最上面寫上回報時應該要注意那些事項
....
-->
## 項目一
<!--- 描述這個項目的意思，或是該如何取的這個項目的資訊 -->
Webpack 的 Issue Template 就有善用此特性。
如果我們希望使用者在填寫重現步驟時，能使用有序條列的方式表達，那我們就可以在該節先將有序清單的 Markdown 語法寫上；如果我們希望使用者在貼上程式碼或是程式輸出的訊息時，能用程式碼區塊包覆起來，我們就可以將相關語法也先寫上。諸如此類，舉例來說就像這樣：
**這個異常的重現步驟**
1.
2.
3.
**當你輸入 `echo $PATH` 後所輸出的訊息**
~~~txt
(paste your output here)
~~~
這部分可以參考 Moby 的 Issue Template。
Issue Description 的部分講到這邊算是告一段落。希望讀者們能透過此主題的文章暸解回報異常時，需要回報哪些資訊，以及其背後的原因。並且能夠將相關知識再轉達給你身邊的工程師、客服、與使用者，讓彼此在溝通上能夠更加順暢，留下更多有效益的回報清單，而不再是一堆想刪又不敢刪議題的尷尬局面。
後話：
原本想說用一天的篇幅就將這個議題講完，沒想到字數還是飆到一萬多字、並分成四天去發表。中間還因為聖誕節和工作進度而不斷擱置，索性在今年的最後一天至少先把這主題補完了，希望這幾篇文章能幫助大家在新的一年更加順利囉。 = )
iThome鐵人賽
看影片追技術