$ git checkout -b freds_fixbug42
$ git am --keep-cr --ignore-whitespace < their-patch-file.patch
在 JIRA 中標記為錯誤的問題單應描述 Clojure 操作不正確的問題,通常會根據文件字串或其他文件產生不正確的結果。一個好的 JIRA 錯誤應具備
一個摘要(標題)描述問題(不是建議的解決方案)和一個說明,其中包含所有適用的以下內容
症狀 - 使用者看到的問題徵兆 - 通常從頂端開始,但可能會移到註解中,以在我們了解實際問題時保留歷史記錄
問題 - 已知問題的陳述
實際結果 - 發生的事情
預期結果 - 應該發生的事情
重現 - 簡潔的內嵌重現(最好不是 github 儲存庫、gist 或連結)
原因 - 意外事件發生的原因
替代方案 - 解決問題的可能方法,以及它們之間的取捨
建議 - 建議的解決方案和任何篩選考量
修補程式 - 實作建議的修補程式名稱
預期是這個問題的新讀者應該能夠從頭到尾閱讀這個問題,並了解為什麼提交這個錯誤、問題、修復方式的思考,以及修補程式中選擇的解決方案。
改善問題通常應與「錯誤」問題類似,但可能沒有重現,因為這是要求增強功能。你應該專注的主要事項是為什麼這個增強功能很重要或值得擁有。一般來說,我們專注於提供使用者達成目標所需的新功能的增強功能,因此請說明你想要做什麼,以及為什麼無法使用現有功能來完成。
「改善」和「新功能」之間的界線有點模糊,不要太過於強調。
如果建議一個已經存在於外部(在熱門公用程式庫中)的功能或公用程式,問題應包含關於現有實作的研究 - 它們有何不同、它們有多熱門、它們的效能如何等。
改善問題越能專注於問題,而不是「新增一個東西」,就能提出越多替代方案,最終的解決方案也會越好。
如果你打算處理分類、預先篩選或篩選的問題,請將受讓人欄位設定為你自己。如果受讓人已經設定為某人,請在問題系統外 ping 他們,或留言並詢問他們是否仍在查看。如果你在幾天內沒有看到回應,你可以變更受讓人。完成後,請務必取消設定受讓人欄位。
這裡的大問題是:「這是一個有效的錯誤/請求嗎?」
分流檢查清單
問題是否正確分類為錯誤(現有功能中的問題)、改進(現有功能的擴充)或新功能(新功能)?
(改進)此問題單是否說明了此建議為何重要,以及影響範圍?例如,使用 https://grep.app 等工具研究公共程式碼庫中建議的公用程式函數的頻率。
(錯誤)此問題單是否包含預期和實際結果的重現?
您是否可以在 Clojure 的目前版本上重現此問題?
這是否為現有問題的重複?
此問題是否實際上是多個問題?
標籤是否正確?請使用現有標籤,並僅在最後不得已時才建立新標籤。
可用的動作
寫下評論和您認為應執行的動作
修改問題單欄位以解決上述問題
如果有多個問題,請建立新問題單並分為多個問題單,適當連結它們
如果沒有問題,請將核准欄位標示為已分流(也留下評論)
準備好分流的問題單:CLJ 開放
這裡的大問題是:「這是一個陳述良好的問題嗎?」
審查檢查清單
分流檢查清單中的所有內容(如果尚未執行)
是否有問題陳述?
所陳述的問題是否真的是一個問題,而不是待辦事項或解決方案?
說明是否良好地分為問題/重現/原因/替代方案/建議/修補程式?
檢閱優先順序欄位 - 是否應調高或調低?有多少人受到影響?如果受到影響,嚴重性為何,是否有解決方法?
如果問題有效能層面,是否有揭露此問題的基準和計時?(應有足夠資訊以在稍後重現任何計時)
可用的動作
寫下評論 - 如果您認為已準備好進行審查,請在評論中說明。如果由於範圍/嚴重性而需要提高關注度,請在評論中提出。
修改說明或其他欄位以解決上述問題
要查看的問題單
CLJ 1.12 候選 - 1.12 的精選候選
這裡的大問題是:「這是一個解決此問題的好方法嗎?」
有時我們會在 Rich 審查問題單之前,透過考慮它是否是一個好的解決方案來「預篩選」它。這有時允許透過預先載入這項工作,讓問題在程序的後續部分快速追蹤。
注意:如果您撰寫了修補程式,您不應預先篩選或篩選該問題單!我們希望有不同的人來審查它。
篩選檢查清單
審查檢查清單中的所有內容
原因 - 一旦了解問題,請盡可能清楚地說明問題的原因
替代方案 - 您應嘗試為任何問題提出多種替代解決方案(對於新功能來說絕對如此)。不要忘記始終存在一種替代方案:什麼都不做。使用問題來找出比較替代方案的維度。考慮以下事項:效能、向下相容性、變更發生的地方等。
建議的解決方案 - 詳細說明所選的替代方案,以及為什麼它是所考慮維度中最好的。建議的解決方案部分應涵蓋修補程式的各個方面,以便審查者在查看程式碼時不會感到驚訝。
修補程式 - 請參閱以下 修補程式評估
效能 - 問題單是否包含足夠的效能考量?如果需要基準,請包含基準和前後時間。如果包含該資料,請在您自己的電腦上驗證它。
建議的部分是否充分說明後續審查者在修補程式中看到的所有內容?
修補程式 - 是否列出建議修補程式的名稱?(這似乎很明顯…直到它不是,所以請務必明確列出它,即使它是唯一的修補程式)
要查看的問題單
CLJ 1.12 候選 - 1.12 的精選候選
CLJ 可篩選 - 在此變更問題單主體之前,請與核心團隊協調(評論永遠沒問題)
若要套用某人的變更,最好建立一個分支並在那裡套用變更
$ 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
元資料
回到原始的重製,並在套用修補程式後重新執行它 - 修補程式是否解決了問題?
閱讀差異,無論是孤立的還是應用於其他地方。驗證它是否與建議的解決方案相符。如果有任何令人驚訝和新奇的事物,則應更新票證或補丁。
補丁是否與周圍程式碼的風格和編碼準則相符?(這些是準則,而不是宇宙的固定法則。)
文件是否仍然正確?
內聯函數在主體中具有類型提示,也需要在內聯函數中提供一些內容