“問題單模板、合理的標(biāo)簽、提交問題單的指導(dǎo)文檔、確保問題單被分類并及時(shí)回應(yīng)，這些對(duì)于開源項(xiàng)目都至關(guān)重要”，Bacon說。
-- Matt Butler
本文導(dǎo)航
-問題單就是用戶的故事 11%
-高質(zhì)量的問題單 39%
-不滿足上述條件的問題單呢?要有約束 49%
-問題單里面有什么？ 58%
-團(tuán)隊(duì)協(xié)同一致 75%
對(duì)于大多數(shù)開源項(xiàng)目來講，問題追蹤系統(tǒng)Issue-tracking system是至關(guān)重要的。雖然有非常多的開源工具提供了這樣的功能，但是大量項(xiàng)目還是選擇了GitHub自帶的問題追蹤器Issue Tracker。
它結(jié)構(gòu)簡(jiǎn)單，可以讓其他人可以非常輕松地參與進(jìn)來，但這才僅僅是開始。
如果沒有適當(dāng)?shù)奶幚恚愕膬?chǔ)存庫repository會(huì)變得很龐大，擠滿重復(fù)的問題單、模糊不明的特性需求單、含混的bug報(bào)告單。項(xiàng)目維護(hù)者會(huì)被大量工作壓得喘不過氣來，新的貢獻(xiàn)者也搞不清楚項(xiàng)目當(dāng)前的工作重點(diǎn)是什么。
接下來，我們一起研究下，如何玩轉(zhuǎn)GitHub的問題單。
問題單就是用戶的故事
我的團(tuán)隊(duì)曾經(jīng)和開源專家 Jono Bacon[1] 做過一次對(duì)話，他是《社區(qū)藝術(shù)》The Art of Community[2]一書的作者、一位戰(zhàn)略顧問、前GitHub社區(qū)總監(jiān)。他告訴我們，高質(zhì)量的問題單是項(xiàng)目成功的關(guān)鍵。有些人把問題單僅僅看作是一堆你不得不去處理的問題列表，但是如果這些問題單管理完善，進(jìn)行了分類并打上標(biāo)簽，會(huì)令人意想不到的提升我們對(duì)代碼和社區(qū)的了解程度，也讓我們更清楚問題的關(guān)鍵點(diǎn)在哪里。
“在提交問題單時(shí)，用戶不太會(huì)有耐心或者有興趣把問題的細(xì)節(jié)描述清楚。在這種情況下，你應(yīng)當(dāng)努力花最短的時(shí)間，盡量多的獲取有用的信息。”，Jono Bacon說。
統(tǒng)一的問題單模板可以大大減輕項(xiàng)目維護(hù)者的負(fù)擔(dān)，尤其是開源項(xiàng)目的維護(hù)者。我們發(fā)現(xiàn)，讓用戶講故事的方法總是可以把問題描述的非常清楚。用戶講故事時(shí)需要說明“是誰，做了什么，為什么而做”，也就是：我是【何種用戶】，為了【達(dá)到何種目的】，我要【做何種操作】。
實(shí)際操作起來，大概是這樣的：
我是一名顧客，我想購買東西，所以我想創(chuàng)建個(gè)賬戶。
我們建議，問題單的標(biāo)題始終使用這樣的用戶故事形式。你可以設(shè)置問題單模板[3]來保證一致性。
問題單模板讓特性需求單保持統(tǒng)一的形式
這個(gè)做法的核心點(diǎn)在于，問題單要清晰的呈現(xiàn)給它涉及的每一個(gè)人：它要盡量簡(jiǎn)單的指明受眾（或者說用戶），操作（或者說任務(wù)），和輸出（或者說目標(biāo)）。不過，不需要過分拘泥于這個(gè)模板，只要能把故事里的是什么事情或者是什么原因說清楚，就達(dá)到目的了。
高質(zhì)量的問題單
問題單的質(zhì)量是參差不齊的，這一點(diǎn)任何一個(gè)開源軟件的貢獻(xiàn)者或維護(hù)者都能證實(shí)。在《The Agile Samurai》[4]中概述過一個(gè)良好的問題單所應(yīng)具備的素質(zhì)。
好的問題單盡量滿足如下條件：
客戶價(jià)值所在
避免使用術(shù)語或晦澀的文字，就算不是專家也能看懂
可以切分，也就是說我們可以逐步解決問題
盡量跟其他問題單沒有瓜葛，依賴其它問題會(huì)降低處理的靈活性
可以協(xié)商，也就說我們有好幾種辦法達(dá)到目標(biāo)
問題足夠小，可以非常容易的評(píng)估出所需時(shí)間和資源
可衡量，我們可以對(duì)結(jié)果進(jìn)行測(cè)試
不滿足上述條件的問題單呢?要有約束
如果一個(gè)問題單很難衡量，或者很難在短時(shí)間內(nèi)完成，你也一樣有辦法搞定它。有些人把這種辦法叫做“約束”（constraints）。
例如，“這個(gè)產(chǎn)品要快”，這種問題單不符合故事模板，而且是沒辦法協(xié)商的。多快才是快呢？這種模糊的需求沒有達(dá)到“好問題單”的標(biāo)準(zhǔn)，但是如果你進(jìn)一步定義一下，例如“每個(gè)頁面都需要在0.5秒內(nèi)加載完”，那我們就能更輕松地解決它了。我們可以把“約束”看作是成功的標(biāo)尺，或者要實(shí)現(xiàn)的里程碑。每個(gè)團(tuán)隊(duì)都應(yīng)該定期的對(duì)“約束”進(jìn)行測(cè)試。
問題單里面有什么？
敏捷方法中，用戶故事里通常要包含驗(yàn)收指標(biāo)或者標(biāo)準(zhǔn)。在GitHub里，建議大家使用markdown格式的清單來概括解決這個(gè)問題單需要完成的任務(wù)。優(yōu)先級(jí)越高的問題單應(yīng)當(dāng)包含更多的細(xì)節(jié)。
比如說，你打算提交一個(gè)關(guān)于新版網(wǎng)站主頁的問題單。那這個(gè)問題單的子任務(wù)列表可能就是這樣的：
使用markdown的清單把復(fù)雜問題拆分成多個(gè)部分
在必要的情況下，你還可以鏈接到其他問題單，以進(jìn)一步明確任務(wù)。（GitHub里做這個(gè)挺方便的）
將特性定義的越細(xì)化，越容易跟蹤進(jìn)度、測(cè)試，最終能更高效的發(fā)布有價(jià)值的代碼。
以問題單的形式收到到問題所在后，還可以用API更深入的了解軟件的健康度。
“在統(tǒng)計(jì)問題單的類型和趨勢(shì)時(shí)，GitHub API可以發(fā)揮巨大作用”，Bacon告訴我們，“如果再做些數(shù)據(jù)挖掘工作，你就能發(fā)現(xiàn)代碼里的問題點(diǎn)、社區(qū)里的活躍成員，或者其他有用的信息。”
有些問題單管理工具提供的API可以提高額外信息，比如預(yù)估時(shí)間或者歷史進(jìn)度。
團(tuán)隊(duì)協(xié)同一致
團(tuán)隊(duì)決定使用某種問題單模板后，如何讓所有人都照做？存儲(chǔ)庫里的ReadMe.md其實(shí)也可以是你們項(xiàng)目的“How-to”文檔。這個(gè)文檔應(yīng)描述清楚這個(gè)項(xiàng)目是做什么的（最好是用可以搜索的語言），以及其他貢獻(xiàn)者應(yīng)當(dāng)如何參與進(jìn)來（比如提交需求單、bug報(bào)告、建議，或者直接貢獻(xiàn)代碼）。
在ReadMe文件里增加清晰的說明，供新協(xié)作者參考
ReadMe文件是提供“問題單指引”的完美場(chǎng)所。如果希望特性需求單遵循“用戶講故事”的格式，那就把格式寫在ReadMe里。如果使用某種跟蹤工具來管理待辦事項(xiàng)，那就標(biāo)記在ReadMe里，這樣別人也能看到。
“問題單模板、合理的標(biāo)簽、提交問題單的指導(dǎo)文檔、確保問題單被分類并及時(shí)回應(yīng)，這些對(duì)于開源項(xiàng)目都至關(guān)重要”，Bacon說。
京公網(wǎng)安備 11010502049343號(hào)