超级账本-如何贡献
个人感受,文档看的再多,学习的速度也不如参与到项目中去,深入了解实现原理和设计的初衷。文档只能让我们对Fabric的整体运行机制有一个宏观的认识,要进一步深入,就需要从源代码入手,而贡献代码则是一个自然而然的事情,学习的过程中总会发现一些问题和值得优化的地方。所以前阵子顺手翻译了一下Fabric如何贡献相关的官方文档。这篇文章讲解,其中的整体流程和所需用到的工具。如需详细学习,请参考官方文档:
- 官方文档
- 官方文档中文版
下面是我个人的官方文档中文版本翻译的GitHub仓库,欢迎大家star:
https://github.com/TopJohn/fabric-docs-cn
同时我会将已经完成的部分同步发Pull Request到hyperledger-labs组织下的fabric-docs-cn仓库中:
https://github.com/hyperledger-labs/fabric-docs-cn
有兴趣的朋友也可以一起参与超级账本国际化相关的工作中来。
贡献的方法
不管作为普通用户还是开发者,这里都有很多为Hyperledger Fabric做贡献的方法。
作为普通用户:
作为开发者:
获取一个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开始你的贡献。
设置开发环境
接下来,在本地开发环境中构建项目,以确保所有配置都是正确的。
什么是更好的变更请求?
大的变更,例如那些大于300行的CR将更有可能收到-2,并且你可能被要求重构以符合本指南。
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官方文档中文版。