操作指引¶

非常感谢能有心为WeCross贡献代码！

社区开发者可以针对代码中的BUG、不足和功能点发起Pull Request(PR)来申请对代码的修改。

社区将牢记每一份来自社区成员的贡献，并且会奖励每一位贡献者。

发起提案¶

改进提案(CIP，CrossChain Improvement Proposals)，是一种遵循一定规范的特殊Issue，用于提出和讨论WeCross的新需求、新特性和新功能。

CIP会对WeCross一个或多个模块的功能特性、接口规范、协议设计和逻辑流程等实现细节进行描述，可以看作是WeCross的设计蓝图。WeCross的项目维护和版本迭代都是通过社区基于CIP讨论和开发完成的。

如何发起CIP¶

要发起一个优秀的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项目版本控制策略。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为你列出了很多合适的开发任务，每一项都标注了难度级别，详见Task挑战介绍。当然里面也会有一些极具挑战的任务，期待极客的你迎难而上，马到功成！

如果你想搞点大事情，例如添加新的功能组件、改变目前的使用方式或者进行较大的项目优化，在实践之前请务必确保你已经在Issue区发起了一个改进提案CIP，并经过了社区的充分讨论和设计。

PR规范¶

为了让你的工作快速得到其它社区成员的理解和认可，每个PR需要你遵循一些比较粗略的约定，例如表达清楚你更改了什么，以及更改的原因。PR的Comment栏建议包含如下内容：

<子系统/模块>: <标注当前PR更改了什么>
<空白行>
<详细描述为什么要这样更改>
<空白行>
Signed-off-by: <你的名字> <你的电子邮箱> 

代码规范¶

WeCross作为开源项目，需要严格把控代码质量，增强其可读性和可扩展性，以便于其它的社区成员理解WeCross代码，并快速地加入项目的开发和维护。

代码风格¶

WeCross项目代码采用Google Java风格，基于Gradle插件google-java-format-gradle-plugin完成代码的格式化，提交PR之前需要执行如下命令格式化代码：

bash gradlew goJF

代码质量¶

WeCross项目发布新版本之前会对代码进行安全扫描和渗透测试。为了避免反复的漏洞修复和检测，在提交PR之前需要使用安全工具扫描代码，并解决报告里的中高危漏洞以及不规范的编程习惯。推荐使用

Sonarlint代码扫描工具，主流的IDE包括Idea和Eclipse都有对应的插件集成。

测试规范¶

为了保证代码的正确性，以及约束后续PR不会影响之前的代码逻辑，对于任何有逻辑改动的PR，都需要添加对应的单元测试。如果该PR为项目新增了功能点，那么还需要添加相应的集成测试以覆盖该功能点。

单元测试¶

以类为界限测试该类中所有方法的正确性，如果涉及到其它类的调用，可以使用单元测试工具Mockito模拟其它类的功能。在编写单元测试时，不仅要关注正确执行的代码流程，还要确保所有异常情况的处理都符合你的预期。务必重视单元测试，从效果上而言，单元测试就像是能执行的文档，描述了在各种条件调用这段代码时，你所期望这段代码完成的功能和效果。

集成测试¶

单元测试的作用收敛在了单个模块或函数，但是 WeCross是复杂的大型项目，还需要集成测试来保证所有模块组合之后整个项目依然符合预期。WeCross中的集成测试由CI触发，会搭建复杂的跨链网络，测试WeCross所有的功能点和周边组件的正确性。