-
Notifications
You must be signed in to change notification settings - Fork 75
操作指引
问问题，报bug：直接提issue
提想法：提交改进提案
写代码：贡献代码流程
改进提案(CIP，CrossChain Improvement Proposals)，是一种遵循一定规范的特殊Issue，用于提出和讨论WeCross的新需求、新特性和新功能。
CIP会对WeCross一个或多个模块的功能特性、接口规范、协议设计和逻辑流程等实现细节进行描述，可以看作是WeCross的设计蓝图。WeCross的项目维护和版本迭代都是通过社区基于CIP讨论和开发完成的。
要发起一个优秀的CIP，你可以借鉴以下的思路：
- 尽可能描述清楚你的动机，它或许不是一个痛点，但很有必要性，那么请让其他的成员也能明白你的想法。你可以通过背景-拟解决的问题-使用的场景这样的结构对你的CIP进行阐述。
- 尽可能的完善你的方案，这并不是必选项，但是却能帮助其他成员快速理解并一起参与你的方案设计。你可以在CIP中描述模块架构、功能列表、协议和接口设计、数据结构以及必要的时序图。
- 当CIP涉及重大功能模块的更改，或者增加了新的特性，那么兼容性和安全分析以及版权声明是不可或缺的，这样整个社区才有信心和底气一起推进该CIP的执行进程。
一个CIP从提出到结束，会有很多的社区成员参与，具体的工作流如下：
- 提案阶段(Proposal)：发起人按照CIP模板，填写CIP的功能简介，提交Issue，由社区审核。
- 方案阶段(Draft)：社区认可该CIP提案后，为该提案赋予
Proposal标签，然后发起人进行CIP补充。期间发起人可以与其他社区成员一起进行多轮沟通，共同完善方案。 - 采纳阶段(Accepted)：发起人完成CIP完善后，社区决定是否采纳该CIP，如果发现还有需要优化的地方，会重新回到Draft阶段。如果确定采纳，社区会将此CIP纳入版本规划，发起者可以一起参与开发。
- 结束(Final)：CIP功能随版本发布后，将该CIP标识为结束状态。
社区由衷感谢每一个CIP发起者，并会提供专属的纪念品。
非常感谢能有心为WeCross贡献代码！
社区开发者可以针对代码中的BUG、不足和功能点发起Pull Request(PR)来申请对代码的修改。
社区将牢记每一份来自社区成员的贡献，并且会奖励每一位贡献者。
贡献代码之前，你需要了解WeCross项目版本控制策略。WeCross采用的是git-flow的工作流程：
- master：最新的稳定分支
- dev：待发布的稳定分支
- feature-xxx：一个正在开发xxx特性分支
- bugfix-xxx：一个正在修复xxx Bug的分支
无论是修复Bug还是开发新特性，都是基于以下流程：
- Fork项目仓库到个人仓库
- 确定好你的工作基础，拉取相应分支并创建一个新分支
- 编写代码以及单元测试，确保所有测试都已通过
- 提交你的工作，具体格式详见之后的PR规范
- CI系统会自动测试所有的提交请求，包括单元测试和集成测试；如果CI报错，请根据错误提示完成更改
- CI通过后，你的PR将会由社区进行审核，他们可能会提出一些修改建议：
- 完成更改后，需要重新审核你的PR
- 如果PR过期，你可以使用GitHub的
update branch按钮 - 如果存在冲突，你可以在本地通过Rebase或者Merge解决，然后强制推送到你的PR分支；你不需要仅为解决冲突而重新审核，但是如果有重大更改，则应该申请重新审核。
- 审核通过后会合并你的PR，感谢你的贡献
如果你已经对WeCross有一定了解，并且希望能够为WeCross贡献代码，Help Wanted Issues为你列出了很多合适的开发任务，每一项都标注了难度级别，详见任务领取介绍。当然里面也会有一些极具挑战的任务，期待极客的你迎难而上，马到功成！
如果你想搞点大事情，例如添加新的功能组件、改变目前的使用方式或者进行较大的项目优化，在实践之前请务必确保你已经在Issue区发起了一个改进提案CIP，并经过了社区的充分讨论和设计。
为了让你的工作快速得到其它社区成员的理解和认可，每个PR需要你遵循一些比较粗略的约定，例如表达清楚你更改了什么，以及更改的原因。PR的Comment栏建议包含如下内容：
<子系统/模块>: <标注当前PR更改了什么>
<空白行>
<详细描述为什么要这样更改>
<空白行>
Signed-off-by: <你的名字> <你的电子邮箱>
WeCross作为开源项目，需要严格把控代码质量，增强其可读性和可扩展性，以便于其它的社区成员理解WeCross代码，并快速地加入项目的开发和维护。
WeCross项目代码采用Google Java风格，基于Gradle插件google-java-format-gradle-plugin完成代码的格式化，提交PR之前需要执行如下命令格式化代码：
./gradlew goJF
WeCross项目发布新版本之前会对代码进行安全扫描和渗透测试。为了避免反复的漏洞修复和检测，在提交PR之前需要使用安全工具扫描代码，并解决报告里的中高危漏洞以及不规范的编程习惯。推荐使用
Sonarlint代码扫描工具，主流的IDE包括Idea和Eclipse都有对应的插件集成。
为了保证代码的正确性，以及约束后续PR不会影响之前的代码逻辑，对于任何有逻辑改动的PR，都需要添加对应的单元测试。如果该PR为项目新增了功能点，那么还需要添加相应的集成测试以覆盖该功能点。
以类为界限测试该类中所有方法的正确性，如果涉及到其它类的调用，可以使用单元测试工具Mockito模拟其它类的功能。在编写单元测试时，不仅要关注正确执行的代码流程，还要确保所有异常情况的处理都符合你的预期。务必重视单元测试，从效果上而言，单元测试就像是能执行的文档，描述了在各种条件调用这段代码时，你所期望这段代码完成的功能和效果。
单元测试的作用收敛在了单个模块或函数，但是 WeCross是复杂的大型项目，还需要集成测试来保证所有模块组合之后整个项目依然符合预期。WeCross中的集成测试由CI触发，会搭建复杂的跨链网络，测试WeCross所有的功能点和周边组件的正确性。