Skip to content

Latest commit

 

History

History
146 lines (92 loc) · 5.53 KB

CONTRIBUTING.zh-CN.md

File metadata and controls

146 lines (92 loc) · 5.53 KB

如何参入贡献

首先我们需要明确的时候,参入开源项目贡献,不仅仅是指提交代码解决 bug,提交 feature,参入开源贡献有很多种的产出结果,包括且不限于:

  1. 提需求:根据自己业务上的需求,确定开源项目无法满足的情况下,详细的提交自己的需求;
  2. 文档:发现文档上的小问题,可以顺手提交 PR 解决,或者提交 issue 提交文档问题以及建议;
  3. 讨论:发起 discussion 讨论自己的想法、需求、建议等;
  4. 答疑:根据自己的使用经验,帮忙回复和处理 issue,discussion;
  5. bugfix:在使用过程中,遇到一些问题,如果能定位到问题的代码,并且愿意尝试接受挑战,可以提交 PR 解决问题;
  6. 提交特性:根据 issue、discussion 的讨论,实现之后提交 PR,为整个开源用户收益;
  7. 生态运营:通过自己的能力,为开源项目添加生态内容,比如:博客、案例、解决方案、扩展包等等;

有任何疑问,欢迎提交 issue,或者直接修改提交 PR。下面主要介绍几类开源贡献的操作指南。

如何本地运行官网代码?

如果想帮忙优化文档,提交图表示例,就一定需要启动官网调试和验证,这里介绍一下如何启动官网。

  • clone 代码到本地
$ git clone [email protected]:antvis/G2.git
  • 安装项目依赖
$ cd G2

$ npm install

也可以按照自己的习惯,选择其他的包管理工具进行安装。

  • 安装官网依赖并启动
$ cd site

$ npm install

$ npm start

然后在命令控制台就能看到访问本地官网的 URL 地址。

如何调试项目代码?

在学习项目的代码,或者为项目解决 bug,提交 feature 的时候,一定会涉及到代码的调试和运行,这里介绍怎么启动和调试项目。

  • clone 项目,并安装依赖
$ git clone [email protected]:antvis/G2.git

$ cd G2

$ npm install
  • 启动本地调试案例

G2 使用了 Vite 来搭建预览环境,通过 npm run dev 可以打开预览界面。

$ npm run dev

预览界面可以预览 __tests__/plots 下面的所有图表案例,并且通过下拉框进行切换。图表案例根据关注点不同,分为以下几类:

在开始开发的时候,首先需要确定即将实现的功能或者修复的 BUG 是属于上面的哪一个分类,然后在对应的分类文件夹下新增一个文件,输入对应的代码,并且在对应的 index.js 导出,这样就可以在预览环境里里面预览了。

  • 本地运行 CI
$ npm run test

上面的命令就可以本地运行 CI,保证修改代码之后,不会带来新的问题。

贡献 PR 的要求是什么?

为了保证项目长期的代码质量和稳定性,一个 PR 需要至少保障一下规范:

  • Commit Message 规范
  • 自动化测试要求
  • Pull Request 规范

Commit Message 规范

根据 angular 规范提交 commit,这样 history 看起来更加清晰,还可以自动生成 changelog。规范格式如下:

type(scope): your commit message subject

type:提交 commit 的类型,包括以下几种:

  • feat: 新功能
  • fix: 修复问题
  • docs: 修改文档
  • style: 修改代码格式,不影响代码逻辑
  • refactor: 重构代码,理论上不影响现有功能
  • perf: 提升性能
  • test: 增加修改测试用例
  • chore: 修改工具相关(包括但不限于文档、代码生成等)
  • deps: 升级依赖

scope:修改文件的范围。

subject:修改的具体内容。

示例

fix(compile): couple of unit tests for IE9

自动化测试要求

G2 的自动化测试有两个部分:

  • 单元测试:测试纯数据模块或者功能,在 __tests__/unit/ 下面。
  • 集成测试:通过截图对比像素,测试整个可视化图表的渲染结果,在 __tests__/integration/ 下面。

对于所有的改动,都需要针对改动点,提交单元测试或者集成测试,保证自己修改的地方能被覆盖到,并且本地运行 npm run test 保证 CI 运行通过。

Pull Request 规范

由于谁也无法保证过了多久之后还记得多少,为了后期回溯历史的方便,请在提交 Pull Request 时确保提供了以下信息。

  1. 需求点(一般关联 issue 或者注释都算)
  2. 升级原因(不同于 issue,可以简要描述下为什么要处理)
  3. 框架测试点(可以关联到测试文件,不用详细描述,关键点即可)
  4. 关注点(针对用户而言,可以没有,一般是不兼容更新等,需要额外提示)

更多其他的疑问,可以提交 discussion 寻求帮助,期望早日成为 AntV 的 contributor。