超簡單玩轉 GitHub 的問題單(issue)

2021-07-25 06:10:17 字數 2733 閱讀 7298

對於大多數開源專案來講,問題追蹤系統是至關重要的。雖然有非常多的開源工具提供了這樣的功能,但是大量專案還是選擇了 github 自帶的問題追蹤器。它結構簡單,可以讓其他人可以非常輕鬆地參與進來,但這才僅僅是開始。如果沒有適當的處理,你的儲存庫會變得很龐大,擠滿重複的問題單、模糊不明的特性需求單、含混的 bug 報告單。專案維護者會被大量工作壓得喘不過氣來,新的貢獻者也搞不清楚專案當前的工作重點是什麼。接下來,我們一起研究下,如何玩轉 github 的問題單。

問題單就是使用者的故事

我的團隊曾經和開源專家 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 說。

超簡單玩轉 GitHub 的問題單(issue)

對於大多數開源專案來講,問題追蹤系統是至關重要的。雖然有非常多的開源工具提供了這樣的功能,但是大量專案還是選擇了 github 自帶的問題追蹤器。它結構簡單,可以讓其他人可以非常輕鬆地參與進來,但這才僅僅是開始。如果沒有適當的處理,你的儲存庫會變得很龐大,擠滿重複的問題單 模糊不明的特性需求單 含混...

完美解決Github網頁開啟超慢的問題

開啟 記錄下查詢到的ip位址。找到 c windows system32 drivers etc目錄下hosts檔案。可以把檔案複製到桌面,用notepad 編輯器開啟修改,修改完成後再放進去。開啟之後新增以下內容。在末尾新增三行記錄並儲存。需管理員許可權,注意ip位址與網域名稱間需留有空格 下圖是...

github的簡單使用

1安裝git後 git config global user.name your name git config global user.email email example.com 2.生成本地的ssh金鑰 開啟shell windows下開啟git bash ssh keygen t rsa ...