Clojure

篩選問題單

如果您有興趣提供修補程式或為 Clojure 做出貢獻,請參閱 開發概觀

篩選的工作是建立一個高品質的問題和建議解決方案串流,以便 BDFL 能夠有效地審查並考慮納入。雖然此頁面使用通用術語「篩選」,但在 工作流程 步驟中,社群和 Clojure 核心團隊可以提供價值的幾個特定地方。

  • 分類 - 評估新進問題單(通常是針對 Ask Clojure 問題而建立)。

  • 審查 - 建立代表良好問題的問題單。

  • 篩選 - 評估問題單和修補程式,以找出解決方案

這些不同的流程在重點上有所不同,但它們有一個共同的目標,就是建立一個問題單,說明所遇到的問題、所考慮的解決方案,以及最後選擇的方法和修補程式。

一個好的「錯誤」問題單是什麼樣子?

在 JIRA 中標記為錯誤的問題單應描述 Clojure 操作不正確的問題,通常會根據文件字串或其他文件產生不正確的結果。一個好的 JIRA 錯誤應具備

一個摘要(標題)描述問題(不是建議的解決方案)和一個說明,其中包含所有適用的以下內容

  • 症狀 - 使用者看到的問題徵兆 - 通常從頂端開始,但可能會移到註解中,以在我們了解實際問題時保留歷史記錄

  • 問題 - 已知問題的陳述

  • 實際結果 - 發生的事情

  • 預期結果 - 應該發生的事情

  • 重現 - 簡潔的內嵌重現(最好不是 github 儲存庫、gist 或連結)

  • 原因 - 意外事件發生的原因

  • 替代方案 - 解決問題的可能方法,以及它們之間的取捨

  • 建議 - 建議的解決方案和任何篩選考量

  • 修補程式 - 實作建議的修補程式名稱

預期是這個問題的新讀者應該能夠從頭到尾閱讀這個問題,並了解為什麼提交這個錯誤、問題、修復方式的思考,以及修補程式中選擇的解決方案。

好的「改善」或「新功能」問題是什麼樣子?

改善問題通常應與「錯誤」問題類似,但可能沒有重現,因為這是要求增強功能。你應該專注的主要事項是為什麼這個增強功能很重要或值得擁有。一般來說,我們專注於提供使用者達成目標所需的新功能的增強功能,因此請說明你想要做什麼,以及為什麼無法使用現有功能來完成。

「改善」和「新功能」之間的界線有點模糊,不要太過於強調。

如果建議一個已經存在於外部(在熱門公用程式庫中)的功能或公用程式,問題應包含關於現有實作的研究 - 它們有何不同、它們有多熱門、它們的效能如何等。

改善問題越能專注於問題,而不是「新增一個東西」,就能提出越多替代方案,最終的解決方案也會越好。

如何「挑選」一個問題

如果你打算處理分類、預先篩選或篩選的問題,請將受讓人欄位設定為你自己。如果受讓人已經設定為某人,請在問題系統外 ping 他們,或留言並詢問他們是否仍在查看。如果你在幾天內沒有看到回應,你可以變更受讓人。完成後,請務必取消設定受讓人欄位。

分類程序

這裡的大問題是:「這是一個有效的錯誤/請求嗎?」

分流檢查清單

  • 問題是否正確分類為錯誤(現有功能中的問題)、改進(現有功能的擴充)或新功能(新功能)?

  • (改進)此問題單是否說明了此建議為何重要,以及影響範圍?例如,使用 https://grep.app 等工具研究公共程式碼庫中建議的公用程式函數的頻率。

  • (錯誤)此問題單是否包含預期和實際結果的重現?

  • 您是否可以在 Clojure 的目前版本上重現此問題?

  • 這是否為現有問題的重複?

  • 此問題是否實際上是多個問題?

  • 標籤是否正確?請使用現有標籤,並僅在最後不得已時才建立新標籤。

可用的動作

  • 寫下評論和您認為應執行的動作

  • 修改問題單欄位以解決上述問題

  • 如果有多個問題,請建立新問題單並分為多個問題單,適當連結它們

  • 如果沒有問題,請將核准欄位標示為已分流(也留下評論)

準備好分流的問題單:CLJ 開放

審查程序

這裡的大問題是:「這是一個陳述良好的問題嗎?」

審查檢查清單

  • 分流檢查清單中的所有內容(如果尚未執行)

  • 是否有問題陳述?

  • 所陳述的問題是否真的是一個問題,而不是待辦事項或解決方案?

  • 說明是否良好地分為問題/重現/原因/替代方案/建議/修補程式?

  • 檢閱優先順序欄位 - 是否應調高或調低?有多少人受到影響?如果受到影響,嚴重性為何,是否有解決方法?

  • 如果問題有效能層面,是否有揭露此問題的基準和計時?(應有足夠資訊以在稍後重現任何計時)

可用的動作

  • 寫下評論 - 如果您認為已準備好進行審查,請在評論中說明。如果由於範圍/嚴重性而需要提高關注度,請在評論中提出。

  • 修改說明或其他欄位以解決上述問題

要查看的問題單

篩選/預篩選程序

這裡的大問題是:「這是一個解決此問題的好方法嗎?」

有時我們會在 Rich 審查問題單之前,透過考慮它是否是一個好的解決方案來「預篩選」它。這有時允許透過預先載入這項工作,讓問題在程序的後續部分快速追蹤。

注意:如果您撰寫了修補程式,您不應預先篩選或篩選該問題單!我們希望有不同的人來審查它。

篩選檢查清單

  • 審查檢查清單中的所有內容

  • 原因 - 一旦了解問題,請盡可能清楚地說明問題的原因

  • 替代方案 - 您應嘗試為任何問題提出多種替代解決方案(對於新功能來說絕對如此)。不要忘記始終存在一種替代方案:什麼都不做。使用問題來找出比較替代方案的維度。考慮以下事項:效能、向下相容性、變更發生的地方等。

  • 建議的解決方案 - 詳細說明所選的替代方案,以及為什麼它是所考慮維度中最好的。建議的解決方案部分應涵蓋修補程式的各個方面,以便審查者在查看程式碼時不會感到驚訝。

  • 修補程式 - 請參閱以下 修補程式評估

  • 效能 - 問題單是否包含足夠的效能考量?如果需要基準,請包含基準和前後時間。如果包含該資料,請在您自己的電腦上驗證它。

  • 建議的部分是否充分說明後續審查者在修補程式中看到的所有內容?

  • 修補程式 - 是否列出建議修補程式的名稱?(這似乎很明顯…直到它不是,所以請務必明確列出它,即使它是唯一的修補程式)

要查看的問題單

修補程式評估

若要套用某人的變更,最好建立一個分支並在那裡套用變更

$ git checkout -b freds_fixbug42
$ git am --keep-cr --ignore-whitespace < their-patch-file.patch
  • 當要修補的檔案包含 DOS CR/LF 行尾時,--keep-cr 有幫助。當不需要時,它似乎無害,但如果您懷疑它會造成問題,請將它關閉或使用 --no-keep-cr。

  • 當自修補程式建立以來,對 master 所做的唯一變更僅為內容列中的空白時,--ignore-whitespace 會有所幫助。如果沒有這個選項,有些修補程式將無法套用。有了這個選項,審查人員可以幫助避免僅因為 master 中的空白有所變更,就讓貢獻者更新修補程式。

  • 如果您遵循此程序來完成貢獻 lib 的貢獻,請改用

$ git am --keep-cr -s --ignore-whitespace < their-patch-file.patch

其中 -s 表示您正在簽署提交。這對於審查不是必要的。

修補程式評估檢查清單

  • 它是一個 .patch 檔案(不是 .diff)嗎?

  • 修補程式作者是 貢獻者 嗎?如果不是,我們無法考慮該修補程式。

  • 修補程式是否有良好的提交註解?應為「CLJ-1234 - 說明」的形式,其中說明應以問題為重點。如果包含更多關於解決方案的詳細資訊,它應遵循標題列。一般來說,我們依賴 jira 來放置所有這些詳細資訊,而不是提交註解,但這些註解也可以(假設它們是正確的!)。

  • 使用 git apply 在本地套用修補程式(有任何空白警告嗎?不一定是大事,但請考慮一下)

  • 執行 mvn clean test - 所有測試都應通過

  • 修補程式是否包含它可以/應該包含的測試?

  • 預設情況下,測試程式碼會以直接連結編譯。如果變更可能在沒有直接連結的情況下出現問題,也請執行 mvn -Ptest-no-direct clean test

  • 測試是否過多(引入對實作細節的依賴性)?

  • 如果有新的命名空間(在 src 或 test 中),可能需要將它們新增到編譯清單中 - 更新 build.xml

  • 對現有核心巨集的變更不應呼叫新函式(這會在較新的編譯程式碼在較舊的執行時期上執行時,產生相容性問題)

  • 對現有核心巨集的變更可能會影響規格 - 如果是這樣,應考慮這一點,並且可能需要一個單獨的 core.specs 修補程式

  • 涉及 Java 互通性的任何變更都應檢查 Java 反射(通常建議在具有互通性的任何 Clojure 命名空間的頂端新增 (set! warn-on-reflection true)

  • 任何新的公開函式都應具有 :added 元資料

  • 回到原始的重製,並在套用修補程式後重新執行它 - 修補程式是否解決了問題?

  • 閱讀差異,無論是孤立的還是應用於其他地方。驗證它是否與建議的解決方案相符。如果有任何令人驚訝和新奇的事物,則應更新票證或補丁。

  • 補丁是否與周圍程式碼的風格和編碼準則相符?(這些是準則,而不是宇宙的固定法則。)

  • 文件是否仍然正確?

  • 內聯函數在主體中具有類型提示,也需要在內聯函數中提供一些內容