超簡單玩轉 GitHub 的問題單（issue）

問題單就是用戶的故事

個人團隊曾經和開源專家 Jono Bacon作過一次對話，他是《社區藝術》一書的做者、一位戰略顧問、前 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 說。

原文來自：https://linux.cn/article-8002-1.html

本文地址：http://www.linuxprobe.com/play-github-issue.html