超級帳本-如何貢獻

原文地址：www.xuanzhangjiong.top/2019/03/12/…

做者：TopJohn

超級帳本-如何貢獻

我的感覺，文檔看的再多，學習的速度也不如參與到項目中去，深刻了解實現原理和設計的初衷。文檔只能讓咱們對Fabric的總體運行機制有一個宏觀的認識，要進一步深刻，就須要從源代碼入手，而貢獻代碼則是一個天然而然的事情，學習的過程當中總會發現一些問題和值得優化的地方。因此前陣子順手翻譯了一下Fabric如何貢獻相關的官方文檔。這篇文章講解，其中的總體流程和所需用到的工具。如需詳細學習，請參考官方文檔：

• 官方文檔原版
• 官方文檔中文版

下面是我我的的官方文檔中文版本翻譯的GitHub倉庫，歡迎你們star：

github.com/TopJohn/fab…

同時我會將已經完成的部分同步發Pull Request到hyperledger-labs組織下的fabric-docs-cn倉庫中：

github.com/hyperledger…

有興趣的朋友也能夠一塊兒參與超級帳本國際化相關的工做中來。

貢獻的方法

無論做爲普通用戶仍是開發者，這裏都有不少爲Hyperledger Fabric作貢獻的方法。

做爲普通用戶：

• 提出功能-改進建議
• 反饋錯誤
• 幫助測試在release roadmap上即將發佈的史詩。將問題經過Jira或者RocketChat反饋給開發者。

做爲開發者：

• 若是你的時間很少，能夠考慮選擇一些想要幫助的任務，參考[修復問題和認領正在進行的任務](#修復問題和認領正在進行的任務) 。

• 若是你能夠全職開發，能夠提一個新的特性（參考提出功能-改進建議）帶領一個團隊來實現它，或者加入在已經存在的史詩中的團隊。若是你在release roadmap發現了一個你感興趣的史詩，請及時經過Jira或者RocketChat聯繫分配到任務的人，和他們一塊兒完成這個史詩。

獲取一個Linux Foundation的帳號

爲了參與到Hyperledger Fabric項目的開發中來，你首先須要一個Linux Foundation帳號。你須要使用你的LF ID來訪問全部的Hyperledger社區的工具，包括 Gerrit，Jira，RocketChat，和Wiki (僅用於編輯)。

項目管理

正如咱們的章程中描述的那樣，Hyperledger Fabric是在一個開放治理的模型下管理的。項目和子項目由一系列維護者主導。一個新的子項目能夠指定一些初始的維護者，當項目第一次被批准的時候，由頂級項目的現有維護者所批准。

維護者

Fabric項目由項目的頂級維護者領導。維護者負責評審和合並提交評審的全部布丁，並在超級帳本技術委員會的方針下指導項目的技術發展路線。

成爲一名維護者

項目的維護者會時不時地考慮添加或者刪除維護者。現有的維護者能夠提交變動到MAINTAINERS.rst文件中。一個提名的維護者能夠由大多數現有的維護者批准經過成爲正式的維護者。一旦批准經過，變動就會被合併同時個體就會在維護者的組中被添加（或者移除）。維護者可能會由於明確的辭職、長時間的不活動（超過3個月或者更長的時間），或者由於違反相關的行爲準則或則持續表現出糟糕的判斷而被移出維護者的隊列。

發佈節奏

Fabric的維護者已經肯定了每一個季度大體的發佈節奏（請參考 releases。咱們也在積極考慮採用LTS（long term support）的發佈過程，雖然這些細節須要由具體的維護者決定。相關細節請參考在Chat的#fabric-maintainers中的討論。

提出功能-改進建議

首先，請回顧一下JIRA確保以前沒有已經開啓或者關閉的相同功能的提案。若是沒有，爲了開啓一個提案，咱們建議建立一個Jira的Epic或者Story，選擇一個最合適的環境，並附上一個連接或者內嵌一個提案的頁面，說明這個特性是作什麼的，若是可能的話，描述一下它應該如何實現。這有助於說明爲何應該添加這個特性，例如肯定須要該特性的特定用例，以及若是實現該特性的好處。一旦Jira的issue被建立了，而且描述中添加了附加的或者內嵌的頁面或者一個公開的可訪問的文檔連接，就能夠向 fabric@lists.hyperledger.org 郵件列表發送介紹性的電子郵件，郵件中附上Jira issue的連接，並等待反饋。

對建議性的特性的討論應該在JIRA issue自己中進行，這樣咱們就能夠在社區中有一個統一的方式來找到這個設計的討論。

得到3個或者更多的維護者對新特性的支持將會大大提升該特性相關的變動申請被合併到下一次發佈的可能性。

維護者會議

維護者會在每隔一週的週三的東部時間9點舉行雙週會議在 Zoom上。請參考community calendar獲取具體信息。

維護者的會議的目的是爲了計劃以及審查發佈的進度，同時討論項目或者子項目的技術以及操做方向上的事宜。

如上所述的新特性/加強建議應該在維護者的會議上進行探討，反饋和接受。

發佈路線

Fabric相關的發佈路線的史詩維護在JIRA上。

交流

咱們使用 RocketChat來進行交流或者實用 Google Hangouts™ 進行屏幕分享。咱們的開發計劃和優先級在JIRA上進行發佈，同時咱們也花大量的時間在mailing list上進行討論才作決定。

貢獻指南

安裝前置條件

在咱們開始以前，若是你尚未這樣作那你可能須要檢查一下您是否已經在將要開發區塊鏈應用或者運行Hyperledger Fabric的平臺上是否安裝了運行所需的環境。

得到幫助

若是你試圖尋找一種途徑來尋找專家援助或者解決一些問題，咱們的 社區老是會爲您提供幫助的。咱們在Chat，IRC(#hyperledger on freenode.net) 以及 mailing lists中均可以找到。咱們大多數人都很樂意提供幫助。惟一愚蠢的是你不去問。問題其實是幫助改進項目的很好的方法，由於它們使咱們的文檔更加清晰。

反饋錯誤

若是你是一個用戶，而且發現了錯誤，請使用JIRA來提交問題。在您建立新的JIRA問題以前，請嘗試搜索是否有人已經提過相似的問題，確保以前沒有人報告過。若是以前有人報告過，那麼你能夠添加評論代表你也指望這個問題被修復。

若是缺陷與安全相關，請遵循Hyperledger安全問題處理流程

若是之前沒有報告過，請建立一個新的JIRA。請嘗試爲其餘人提供足夠多的信息以重現該問題。該項目的維護人員應該在24小時以內回覆您的問題。若是沒有，請經過評論提出問題，並要求對其進行評審。您還能夠在Hyperledger Chat中將問題發佈到相關的相關的Hyperledger Fabric的頻道中。好比，能夠將一個文檔問題在 #fabric-documentation中進行廣播，一個數據存儲問題能夠在#fabric-ledger中廣播，以此類推。

提交你的修復

若是你在JIRA上提交了你剛剛發現的問題，並但願修復它，咱們很樂意而且很是歡迎。請將JIRA問題分配給本身，而後您能夠提交變動請求（CR）。

若是你在提交第一個CR的時候須要幫助，咱們已經爲你建立了一個簡短的教程。

修復問題和認領正在進行的任務

查看問題列表找到你感興趣的內容。您也能夠從求助 列表中尋找。明智的作法是從相對直接和可實現的任務開始，而且這個任務是未被分配的。若是沒有分配給別人，，請將問題分配給本身。若是你沒法在合理的時間內完成，請加以考慮而且取消認領，若是你須要更多的時間，請添加評論加以說明，你正在積極處理問題。

審覈提交的變動請求(CRs)

另外一種貢獻和了解Hyperledger Fabric的方法是幫助維護人員審查開放的CR。實際上維護者是相對困難的，他們須要審查全部正在提交的CR而且評估他們是否應該被合併。您能夠查看代碼或則文檔修改，測試更改的內容，並告知提交者和維護者您的想法。完成審覈或測試後，只須要添加評論和投票，便可完成回覆CR。評論「我在系統X上嘗試過這個CR，是正確的」或者「我在系統X上運行這個CR發現了一些錯誤」將幫助維護者進行評估。所以，維護人員也可以更快地處理CR，而且每一個人都能從中獲益。

瀏覽 Gerrit上開放的CRs開始你的貢獻。

設置開發環境

接下來，在本地開發環境中構建項目，以確保全部配置都是正確的。

什麼是更好的變動請求?

• 一次只包含一個變動。不是五個，3個，或者10個。僅僅一個變動。爲何呢？由於它變動的影響範圍。若是咱們有一輪迴歸，那麼將更容易證實一次影響較廣的組合提交將是一個罪魁禍首。

• 在JIRA的故事中包含一個連接。爲何？由於 a) 咱們但願追蹤你的速度以便更好地判斷咱們能夠傳遞什麼信息。b) 由於咱們能夠證實此次變動是有效的。在不少狀況下，會有不少討論圍繞提交的變動，咱們但願將它連接到它的自己。

• 每次變動都包含單元或者集成測試（或者對已有測試的修改）。這不只僅意味着正確的測試。一樣包括一些異常測試來捕獲錯誤。在你寫代碼的時候，你有責任去測試它而且證實你的變動是正確的。爲何呢？由於沒有這些，咱們沒法知道你的代碼是否真的正確地工做。

• 單元測試須要沒有額外的依賴。你應該使用 go test 或者等價的語言的測試方式來運行單元測試。任何須要額外依賴的測試（例如須要用腳原本運行另外一個組件）須要適當的mocking。任何除了單元測試之外的測試根據定義都是集成測試。爲何？由於不少開源軟件開發者都實用測試驅動的開發方式。他們關注一個目錄下的測試用例，一旦代碼變動了他們採用測試去判斷他們的代碼是否正確。這是很是高效的，相比當代碼變動後運行整個項目來講。請參考單元測試的定義在腦海中創建單元測試的標準，以此來寫出高效的單元測試。

• 每一個CR的最小代碼行數。爲何？由於維護者天天一樣也有工做。若是你發送1000或者2000行的代碼，你認爲維護者須要多久才能審查完你的代碼？保證你的變動在200-300行左右，儘量地。若是你有一個比較大的變動，能夠將它分解爲比較小的幾個無關的變動。若是要添加一組新功能來知足一個需求，請在測試中分別添加它們，而後編寫知足需求的代碼。固然，總會有之外。若是你增長一些小變更而後添加了300行測試，你將會被寬恕;-)若是你須要作一個變動，並且影響比較廣或者生成了不少代碼（protobufs等）。一樣也是個例外。

大的變動，例如那些大於300行的CR將更有可能收到-2，而且你可能被要求重構以符合本指南。

• 不要堆疊你的變動請求（例如在先前的變動請求的本地分支提交你的變動）除非它們是相關聯的。這將最大幅度減小合併衝突，而且更快地合併。若是你堆疊你的變動請求，因爲前面的請求中的審覈註釋，你後續的請求將被擱置。

• 寫一個有意義的提交信息。包括55個或者更少字符的標題，後面跟一行空行，而後跟上更全面的關於變動的描述。每一個變動必須包括對應的變動的JIRA標識號(例如[FAB-1234])。這個能夠在標題中，可是一樣須要包括在消息正文中。

Gerrit會自動建立超級連接到JIRA的條目。例如


    [FAB-1234] fix foobar() panic

    Fix [FAB-1234] added a check to ensure that when foobar(foo string)
    is called, that there is a non-empty string argument.
複製代碼

最後，要有迴應。不要讓一個變動請求由於應爲評審意見而不了了之，這樣會致使它須要進行rebase。這隻會進一步延遲合併，給你帶來更多的工做-以修復合併衝突。

法律材料

注意: 每個源文件必須包括Apache Software License 2.0。能夠參考 license header。

咱們儘量努力讓貢獻邊等簡單。這個協議爲咱們提供了貢獻相關的法律相關的知識。咱們使用和Linux® Kernel社區同樣的管理貢獻的方法Developer's Certificate of Origin 1.1 (DCO)來管理Hyperledger Fabric。

咱們只要求在提交要審查的補丁時，開發者在commit消息中帶上他們的sign-off簽名便可。

這裏是一個Signed-off-by line的簽名例子，指示了提交者接受DCO約定：

Signed-off-by: John Doe <john.doe@example.com>
複製代碼

你可使用 git commit -s 在提交的時候來自動帶上你的簽名。

相關的主題

• 維護者
• 使用Jira來了解當前的工做流項
• 設置開發環境
• 構建Hyperledger Fabric
• 配置
• 申請一個Linux Foundation帳號
• 使用Gerrit進行工做
• 使用Gerrit進行審覈
• 查看待定的更改
• 提交一個變動到Gerrit
• 審查變動
• Gerrit 最佳實踐
• 編程指南
• 生成 gRPC 代碼
• 添加或者更新Go第三方包

總結

若是須要查看上述相關的文檔，我也已經爲你們作了翻譯，須要詳細查看每一個細節的朋友能夠查看中文文檔，或者點擊我博客右側的ARCHIEVEMENT之Fabric官方文檔中文版。