摘要：原文地址作者超級賬本如何貢獻個人感受，文檔看的再多，學習的速度也不如參與到項目中去，深入了解實現原理和設計的初衷。維護者負責評審和合并提交評審的所有布丁，并在超級賬本技術委員會的方針下指導項目的技術發展路線。

原文地址：https://www.xuanzhangjiong.to...
作者：TopJohn

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

官方文檔原版

官方文檔中文版

下面是我個人的官方文檔中文版本翻譯的GitHub倉庫，歡迎大家star：

https://github.com/TopJohn/fa...

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

https://github.com/hyperledge...

有興趣的朋友也可以一起參與超級賬本國際化相關的工作中來。

不管作為普通用戶還是開發者，這里都有很多為Hyperledger Fabric做貢獻的方法。

作為普通用戶：

提出功能-改進建議

反饋錯誤

幫助測試在release roadmap上即將發布的史詩。將問題通過Jira或者RocketChat反饋給開發者。

作為開發者：

如果你的時間不多，可以考慮選擇一些想要幫助的任務，參考修復問題和認領正在進行的任務 。

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

為了參與到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的時候需要幫助，我們已經為你創建了一個簡短的教程。

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

另一種貢獻和了解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 

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

維護者

使用Jira來了解當前的工作流項

設置開發環境

構建Hyperledger Fabric

配置

申請一個Linux Foundation賬號

使用Gerrit進行工作

使用Gerrit進行審核

查看待定的更改

提交一個變更到Gerrit

審查變更

Gerrit 最佳實踐

編程指南

生成 gRPC 代碼

添加或者更新Go第三方包

如果需要查看上述相關的文檔，我也已經為大家做了翻譯，需要詳細查看每個細節的朋友可以查看中文文檔，或者點擊我博客右側的ARCHIEVEMENT之Fabric官方文檔中文版。