超级帐本-如何贡献

原文地址：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官方文档中文版。