如何向尤拉作業系統社群提交一個好 PR?

語言: CN / TW / HK

什麼是 PR?借用知乎上的一個回答:用類比的方法來解釋一下 pull reqeust。想想我們中學考試,老師改卷的場景吧。你做的試卷就像倉庫,你的試卷肯定會有很多錯誤,就相當於程式裡的 bug。老師把你的試卷拿過來,相當於先 fork。在你的卷子上做一些修改批註,相當於 git commit。最後把改好的試卷給你,相當於發 pull request,你拿到試卷重新改正錯誤,相當於 merge。

pull request 簡稱為 PR,在不同的系統中 PR 有不同的名字,有些系統中使用 MR 即 merged request 來表示 PR。

以 Gitee 為例,一個 PR 由以下幾部分:標題、內容以及其評論、提交的程式碼和檔案組成。

為什麼說 PR 很重要?

首先,PR 是質量保證體系的基石。因為 PR 是真正合入程式碼,合入更新的入口,直接影響到專案最終交付件的質量。

其次,PR 是大規模協作開發的基石。尤拉社群的協作是在一個互不相見的“虛擬世界”,PR 幾乎是大家交流最重要的通道了。是一種“交流”的語言。

最後,由於社群不會刪除任何的 PR,每一個 PR 都記錄在歷史中,是社群文化的傳承載體之一。PR 的規範與否將會成為社群的一種社群文化,對社群的發展起著至關重要的作用。

糟糕的 PR 是什麼樣子?

既然 PR 如此重要,那麼我們應該如何提交一個好的 PR 呢?在回答這個問題之前,先給大家看一下一個糟糕的 PR 是怎樣的。

通過上面這個示例展示的是最糟糕的 PR 了,我們從 PR 標題可以看到,這是是一個要新增 zhongkeyi 作為一個 Maintainer 的 PR。PR 的內容幾乎就是把標題複製了一遍,沒有其他任何有效資訊。

那麼如何將這個非常糟糕的 PR,變成一個符合社群 PR 提交規範的 PR 呢?以下幾個方面供參考:

  1. 標題只講了新增 zhongkeyi 這個 Maintainer,需要講清楚為什麼要新增這個 Maintainer。
  2. 目前該 SIG 組的專案並不是很多,Maintainer 已經足夠多了,為什麼還要引入這個 Maintainer ?
  3. 這個 Maintainer 在後續專案中的分工和工作是什麼?

以上這些資訊都需要在 PR 中講清楚。我將這些資訊反饋給提交的 PR 的開發者,得到了如下的回覆:

  1. 目前該 SIG 組有兩個 Maintainer 負責硬體加速模組,新加入的 Maintainer 和 SIG 組的其他兩個人負責軟體加速。
  2. 後續考慮增加壓縮庫、hyperscan 等遷移工作,然後拓展其他專案,並且這位 Maintainer 非常積極,所以申請將他增加為 Maintainer。

這是非常糟糕的一類 PR 了,開局一個標題,其他全靠猜。

接下來讓我們看一下第二個例子。

上面這個 PR 的標題完整,PR 的內容也對要建倉的這個軟體做了一些比較簡短的描述,對於該軟體的用途也做了簡短的說明,看起來沒有任何問題。

但是既然是要建立一個軟體倉庫,那麼首先要回答的一個問題就是:為什麼要建立這個倉庫?是對這個軟體有重量級的開發需求?現在加入的是 GCC 10.3 ,那麼以後的 GCC 11.3 的時候,是不是還是要建倉?是不是通過分支來進行版本控制更為穩妥,而不是一個版本建立一個倉庫 。

讓我們看一下第三個例子。

這個 PR 看起來幾乎是一個完美的 PR,標題描述清晰、內容描述詳實,PR 關聯的 issue 也都完整。

從 PR 情況來看,這個軟體不錯,但是需要回答另外一個問題:為什麼要引入這個軟體,軟體好顯然不是一個理由,因為好軟體成千上萬,為什麼我們要單單引入這個軟體?

從 PR 的提交者的回覆來看,這個軟體是來自於中國郵政的一個業務需求。需要尤拉作業系統合入並且做一些適配工作。把這段話加入到 PR 的開頭,就是一個非常完美的 PR 了。

糟糕的 PR 帶來的影響

一個糟糕的 PR 必然會:

  1. 使工作效率降低,增加了無畏的資源消耗。
  2. 延長審批的時間,增加 commiter 和 Maintainer 雙向不滿。
  3. 會影響發行版的質量。
  4. 極大增加了工程師白頭、禿頭和肥胖性工傷的機率

總結:如何寫一個好的 PR?

總結一下,如果你想讓自己提交的 PR 快速讓 Maintainer 合入,以下幾點你可以嘗試一下:

  1. 一個 PR 對應一件事兒,不要把不同的事情放在一個 PR 中,保持 PR 的總結。舉個例子:你不能把增加 Maintainer 和增加軟體倉這兩件事兒放到一個 PR 中,這種 PR 的一定會被拒絕掉的。
  2. PR 首先要說清楚“為什麼”。為什麼會提交這個 PR?這個 PR 解決了什麼問題?
  3. PR 中的描述要清晰明瞭,講清楚 commit 中的要點。
  4. 最好採用分行等形式將 PR 整理清楚,便於閱讀。
  5. 一般來說,一個 PR 必須要有一個 issue 對應。這樣才能夠形成需求和開發程式碼之間的對應關係。

下面讓我們來看一個比較好的 PR 的例子。

從上面那個 PR 可以看到:

  1. 標題很清晰:更新安全委員會成員名單和例會週期
  2. 可讀性很好:分了三段,每一部分做了什麼都很清晰。
  3. 需要誰來檢視寫得很清楚。

總的來說,一個 PR 寫得好的碼農未必能成長為一個偉大的碼農,但是一個 PR 寫不好的碼農註定無法成為一個偉大的碼農。

讓我們從寫好每一個 PR 開始。

參考:

1. https://www.zhihu.com/question/21682976/answer/79489643



本文分享自微信公眾號 - openEuler(openEulercommunity)。
如有侵權,請聯絡 [email protected] 刪除。
本文參與“OSC源創計劃”,歡迎正在閱讀的你也加入,一起分享。