如何寫就完美 Pull Request

譯註：Github Blog 發表了一篇文章 How to write the perfect pull request，對書寫 Pull Request 文案給了些至關不錯的建議。祝願你們都能寫一手好文檔，溝通愉快！

隨着公司規模增加，人和項目都在變化。在 Github，咱們的經驗是常常提醒本身溝通的目標很是有助於保持溝通的高效率，爲此咱們最近提出了一份關於提交 Pull Request 的指南，幫助你們在使用 Pull Request 時能更好地協做。

撰寫 Pull Request

• 要涵蓋這次 Pull Request 的目標，例如：
  嘗試用 XXX 方法實現……
優化……
修復在 XX 狀態下對 XX 的異常處理
• 能夠提供一份關於這些工做原由的說明（包含上相關連接）。不要假定對方已經熟悉這些事情的來龍去脈。
• 記住公司裏任何人都有可能來閱讀這個 Pull Request，因此內容和語氣都須要面向那些未參與工做內容的人，如今和將來的。
• 若是有的話，請詳述你須要的反饋，如：快速過目一下代碼/討論某項技術實現/對設計的意見等等。
• 明確你什麼時候須要反饋。若是這個 PR 還在沒有完成，就須要這麼註明一下。給標題加上[WIP]（施工中）的前綴也是個簡便快捷的方法。
• @艾特 須要特別指明加入討論的人，並說明緣由（「/cc @hax 麻煩來看下這個邏輯對麼？」）。
• 一樣的方法也能夠艾特團隊（「/cc @baixing/sa 這麼作沒安全問題吧？」）。

提供反饋

• 首先要了解下此 PR 的前情提要。
• 若是你有強烈的反對意見，多花幾分鐘審視下本身的意見再作反饋。Think Twice。
• 詢問，不要指點。（「爲何你要……」而非「不要……」）
• 解釋你提出修改意見的緣由。（和代碼規範不符？我的喜愛？）
• 提供簡化或改進代碼的方法。
• 在提到別人的工做成果時避免使用貶義詞（愚蠢什麼的）。
• 謙遜。（「我不很肯定，不過能夠試試……」）
• 不要誇張。（「任什麼時候候絕對……」）
• 評論旨在提升專業技能、產品質量，達成團隊共識。
• 在線交流時要小心負面歧義（若是文字內容中性，咱們傾向認爲語氣偏負面），儘可能使用積極的語氣而非中性的。
• 善用表情符號美化語氣。（感覺一下 「看起來不錯。」 和 「看起來不錯 ^O^」）[譯註1]

對反饋的回覆

• 考慮以感激做爲開場白，尤爲是當反饋混雜了各類意見的時候。
• 若有不明白的地方，請求進一步澄清。（「我不大明白，你能再解釋一下麼？」）
• 提供澄清。解釋對方詢問的實現方案是如何決策的。
• 儘可能回覆全部評論。
• 連接到相關的後續提交。（「好建議！a1da2324ca 已搞定 :D」）
• 若是疑惑和爭論持續擴大，首先審視本身在前面的討論中是否表達良好，嘗試面對面作充分溝通，以後把線下溝通的內容彙總回覆（便於其餘人跟蹤進展或將來了解詳情）。

這份指南部分受到了 ThoughtBot 的 Code Review 指南的啓發。

這份指南很適合咱們的工做方式，以及咱們想要創建的協做文化，但願對你也有幫助。

溝通愉快！

[譯註1]: Github Blog 原文使用了 emoji 語氣無比歡快可愛，sf.com 暫不支持，請至原文感覺那兩句 「looks good」 的區別。