玩轉 GitHub 的問題單（issue）

對於大多數開源項目來講， 問題追蹤系統 （ Issue-tracking system ） 是至關重要的。雖然有非常多的開源工具提供了這樣的功能，但是大量項目還是選擇了 GitHub 自帶的 問題追蹤器 （ Issue Tracker ） 。

它結構簡單，可以讓其他人可以非常輕鬆地參與進來，但這才僅僅是開始。

如果沒有適當的處理，你的 儲存庫 （ repository ） 會變得很龐大，擠滿重複的問題單、模糊不明的特性需求單、含混的 bug 報告單。項目維護者會被大量工作壓得喘不過氣來，新的貢獻者也搞不清楚項目當前的工作重點是什麼。

接下來，我們一起研究下，如何玩轉 GitHub 的問題單。

問題單就是用戶的故事

我的團隊曾經和開源專家 Jono Bacon 做過一次對話，他是 《社區藝術》 （ The Art of Community ） 一書的作者、一位戰略顧問、前 GitHub 社區總監。他告訴我們，高質量的問題單是項目成功的關鍵。有些人把問題單僅僅看作是一堆你不得不去處理的問題列表，但是如果這些問題單管理完善，進行了分類並打上標籤，會令人意想不到的提升我們對代碼和社區的了解程度，也讓我們更清楚問題的關鍵點在哪裡。

「在提交問題單時，用戶不太會有耐心或者有興趣把問題的細節描述清楚。在這種情況下，你應當努力花最短的時間，盡量多的獲取有用的信息。」，Jono Bacon 說。

統一的問題單模板可以大大減輕項目維護者的負擔，尤其是開源項目的維護者。我們發現，讓用戶講故事的方法總是可以把問題描述的非常清楚。用戶講故事時需要說明「是誰，做了什麼，為什麼而做」，也就是：我是【何種用戶】，為了【達到何種目的】，我要【做何種操作】。

實際操作起來，大概是這樣的：

我是一名顧客，我想購買東西，所以我想創建個賬戶。

我們建議，問題單的標題始終使用這樣的用戶故事形式。你可以設置問題單模板來保證一致性。

問題單模板讓特性需求單保持統一的形式

這個做法的核心點在於，問題單要清晰的呈現給它涉及的每一個人：它要盡量簡單的指明受眾（或者說用戶），操作（或者說任務），和輸出（或者說目標）。不過，不需要過分拘泥於這個模板，只要能把故事裡的是什麼事情或者是什麼原因說清楚，就達到目的了。

高質量的問題單

問題單的質量是參差不齊的，這一點任何一個開源軟體的貢獻者或維護者都能證實。在《The Agile Samurai》中概述過一個良好的問題單所應具備的素質。

好的問題單盡量滿足如下條件：

• 客戶價值所在
• 避免使用術語或晦澀的文字，就算不是專家也能看懂
• 可以切分，也就是說我們可以逐步解決問題
• 盡量跟其他問題單沒有瓜葛，依賴其它問題會降低處理的靈活性
• 可以協商，也就說我們有好幾種辦法達到目標
• 問題足夠小，可以非常容易的評估出所需時間和資源
• 可衡量，我們可以對結果進行測試

不滿足上述條件的問題單呢? 要有約束

如果一個問題單很難衡量，或者很難在短時間內完成，你也一樣有辦法搞定它。有些人把這種辦法叫做「約束」（constraints）。

例如，「這個產品要快」，這種問題單不符合故事模板，而且是沒辦法協商的。多快才是快呢？這種模糊的需求沒有達到「好問題單」的標準，但是如果你進一步定義一下，例如「每個頁面都需要在 0.5 秒內載入完」，那我們就能更輕鬆地解決它了。我們可以把「約束」看作是成功的標尺，或者要實現的里程碑。每個團隊都應該定期的對「約束」進行測試。

問題單裡面有什麼？

敏捷方法中，用戶故事裡通常要包含驗收指標或者標準。在 GitHub 里，建議大家使用 markdown 格式的清單來概括解決這個問題單需要完成的任務。優先順序越高的問題單應當包含更多的細節。

比如說，你打算提交一個關於新版網站主頁的問題單。那這個問題單的子任務列表可能就是這樣的：

使用 markdown 的清單把複雜問題拆分成多個部分

在必要的情況下，你還可以鏈接到其他問題單，以進一步明確任務。（GitHub 里做這個挺方便的）

將特性定義的越細化，越容易跟蹤進度、測試，最終能更高效的發布有價值的代碼。

以問題單的形式收到到問題所在後，還可以用 API 更深入的了解軟體的健康度。

「在統計問題單的類型和趨勢時，GitHub API 可以發揮巨大作用」，Bacon 告訴我們，「如果再做些數據挖掘工作，你就能發現代碼里的問題點、社區里的活躍成員，或者其他有用的信息。」

有些問題單管理工具提供的 API 可以提高額外信息，比如預估時間或者歷史進度。

團隊協同一致

團隊決定使用某種問題單模板後，如何讓所有人都照做？存儲庫里的 ReadMe.md 其實也可以是你們項目的 「How-to」 文檔。這個文檔應描述清楚這個項目是做什麼的（最好是用可以搜索的語言），以及其他貢獻者應當如何參與進來（比如提交需求單、bug 報告、建議，或者直接貢獻代碼）。

在 ReadMe 文件里增加清晰的說明，供新協作者參考

ReadMe 文件是提供「問題單指引」的完美場所。如果希望特性需求單遵循「用戶講故事」的格式，那就把格式寫在 ReadMe 里。如果使用某種跟蹤工具來管理待辦事項，那就標記在 ReadMe 里，這樣別人也能看到。

「問題單模板、合理的標籤、提交問題單的指導文檔、確保問題單被分類並及時回應，這些對於開源項目都至關重要」，Bacon 說。

記住一點：這不是為了完成工作而做的工作。這是讓其他人更輕鬆的發現、了解、融入你的社區而設立的規則。

"關注社區的成長，不僅要關注參與開發者的的數量增長，也要關注那些在問題單上幫助我們的人，他們讓問題單更加明確、保持更新，這是活躍溝通和高效解決問題的力量源泉"，Bacon 說。

via: https://opensource.com/life/16/7/how-take-your-projects-github-issues-good-great

作者：Matt Butler 譯者：echoma 校對：jasminepeng

本文由 LCTT 原創翻譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive