Review Board的幾點使用體會

近期產品線研發體系正式將Review Board這款優秀的基於Web的程式碼檢閱開源工具引入到開發過程中，作為產品線內各項目組進行程式碼檢閱的協助工具輔助。我對Review Board近兩年多的關注總算沒有白費，算是有了一個還算不錯的結果。不過Review Board的正式使用並不代表一種結束，反而恰恰是一個新的開始。我們下一步要關注的是如何用好Review Board，讓它真真正正地為改善產品品質和開發效率出力。

在“關於線上程式碼檢閱的幾點考量”這篇博文中我提到了線上程式碼檢閱工具在開發過程中所處的角色、使用時機以及使用時的注意事項，不過當時也多是憑直覺有感而發。真正用了Review Board這樣的評審工具後，有些想法還要進一步細化。

的確，我們在近一個多月的使用過程中發現了許多問題，在公司內部我把這些問題以及解決方案整理成了一頁Wiki Page放到了產品線的知識庫中，這裡我也和大家分享一下。

下面是我整理的關於如何用好Review Board的一個Tips列表：

* 務必保持每個Review Request內容的內聚性
如果你提交一個Review Request，其中包含了對A庫的bugfix，給B庫增加一個新feature，以及對C庫重構的一段代碼，那你的這個Review Request就是不合格的。該Request內容上包含了三個不相干的內容，嚴重缺乏內聚，這會給後續評審帶來不良影響，諸如評審者關注點分散，效率下降；評審者不願理睬這種Request等等。對於上述的問題Request，建議拆分為三個Request，讓每個Request內容單一內聚。

* 請為你的Review Request設定評審結束時間
切記為每個Review Request設定一個有效評審時間範圍，否則你的評審將被視為永遠有效，這樣的Request久而久之就會變成"塑料製品垃圾"塞滿你的Dashboard。由於Review Board上似乎沒有設定評審截止時間的位置，所以一般可在Description中增加該Request對應的評審結束時間，例如加上：
"評審截止時間：2011-03-07 12:00"

* 保持你的Dashboard Clean，別忘了關閉你的Review Request
使用Review Board一段時間後，你就會發現你的Dashboard中有很多Incoming和Outgoing的 Requests，讓人心生不悅。建議大家在Request評審完畢或到期後關閉你發起的Request，保持Dashboard的clean。

在每個Request裡有一個close標籤，下面有三個選項：
 - summited 表示評審結束，代碼已經提交，不須繼續評審
 - discarded 丟棄的評審請求
 - delete permanently 應該刪除的請求
一般我們會用到summited。

* 請為評審請求選擇適當的干係人列表
每個評審請求都應該有特定的干係人列表，不要泛泛的發給Review Board系統中設定的所有Group。否則你既不會收到那些不相干人的有效評審，還幹擾了對方的工作。

一般來說發起程式碼檢閱請求前先要明確此次評審的目的，無非以下幾種或它們的組合：
 - 希望相關干係人找出代碼中的代碼邏輯缺陷；
 - 希望相關干係人找出代碼中的商務邏輯缺陷；
 - 分享你的代碼，將你的代碼中的美展現給大家。
明確了目的之後，想必你就應該清楚干係人列表中究竟該有誰了。

* 請評審者聚焦本次Request中的變動
在Review Board實際使用過程中，常常發現這樣的情況：某位同事發起一段針對遺留代碼修改的評審請求。很多評審者給出的一些評審意見針對的卻並非是本次修改的代碼，而是此次變更源碼檔案中的其他代碼。這樣可能會導致下面兩個問題：
 - 提交Request的評審人很可能無法修正非本Request之外的代碼問題；
 - 評審過程可能因此被拉長，很可能無法在截止時間內完成此次評審，甚至可能反覆多次，造成效率上的浪費。
針對這種情況，我們建議評審者聚焦本次改動。如果評審過程中發現其他非本次改動相關的問題，可通過向代碼所在的項目的Todolist或某種問題跟蹤系統提交一個issue/ticket，後續由該項目的主維護者統一安排處理。

最後說說post-review這個工具的使用。Review Board的原理其實就是評審diff檔案。一般情況下大家通過Review Board提供的web頁面提交自己手動產生的diff檔案，這種方法無可厚非。不過Review Board官方還推薦使用另外一種更有效率的方法，那就是使用post-review指令碼發起Review Request。以下內容描述了工作中常見的三種使用post-review工具的情形，前提是你已經將post-review安裝到你的主機上了。

* 在代碼Commit前發起評審請求
有些時候，項目要求代碼未經評審不允許commit到Code Repository中，這種情況我們稱之為pre-commit review。這種情況下可以這樣來發起一個Review Request，先在你的本地程式碼程式庫拷貝中完成對代碼的修改，然後進入到你的本地代碼目錄，執行：
post-review –server=http://xxx.xxx.xxx.xxx/reviews

post-review就會將目前的目錄以及其子目錄下所有變更作為一個diff提交到Review Board形成一個Request Draft等待你的發布。當然你也可以通過post-review直接設定Request的Descripton等欄位，並可通過增加–publish參數立刻發布該Request。

* 代碼commit後發起評審請求
有些時候，某些代碼是在提交到Code Repository後才評審的，這種情況我們稱之為post-commit review。我們可通過版本庫的revision number間的差異來構造Review Request，具體方法如下：
post-review –server=http://xxx.xxx.xxx.xxx/reviews –revision-range=n:m –branch=YOUR_REPOSITORY_PATH
當然你也可以不指定–branch，不過需要在你本地程式碼程式庫拷貝目錄下執行post-review。

* 更新已存在的評審請求
已經提交到Review Board的請求經過評審後，可能需要你再次修改代碼並更新diff檔案以繼續評審。這時你可以通過指定已存在的Review Request id的方式更新已存在Request的diff，方法如下：
post-review –server=http://xxx.xxx.xxx.xxx/reviews ….. –review-request-id=58

注意，如果你的unix/linux賬戶下設定了http_proxy環境變數，那麼在執行post-review之前需要將http_proxy設定為空白，否則post-review的請求將被代理攔截而失敗。

部門裡越來越多的人開始關注和使用Review B