[[179165]]

對于大多數開源項目來講，問題追蹤系統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 說。