贡献者准则

基于团队达成的共识，贡献代码和文档需要遵守一定准则。

Git 分支管理

如上图所示，我们基于较为简单的策略来管理分支和进行发布：

main：主分支、稳定分支、发布分支
develop：开发分支

首先，main 分支用来进行发布操作，所以该分支的代码是稳定、可靠的，develop 分支代表正在进行开发中的任务，需要合并到 main 分支后才可以提供业务上线应用。

另一方面，对于一些持续周期比较长的任务，将其分为两类，一类为功能开发，基于 develop 分支创建新的功能分支 feature/xxx，另一类为漏洞修复，基于 develop 分支创建新的修复分支 fix/xxx，其最终都需要先合并到 develop 分支，再合并到 main 分支才能发布。

信息

优秀的 Git 项目分支管理策略参考：

风格指南

Git 提交信息格式

JavaScript/TypeScript

JavaScript/TypeScript 代码利用 ESLint 进行 Lint，配置更改需要团队达成共识。

使用 VS Code，可以安装 ESLint 和 Prettier 扩展。

在 ESLint 配置之外，还须遵守以下命名规范：

使用驼峰命名法；

// Bad
let bar_chart;

// Good
let barChart;

除类文件需要首字母大写以外，其它（文件夹、文件）均需要首字母小写；

// Bad
src/
├── Core/
|   └── event.ts
└── util/
    └── Math.ts

// Good
src/
├── core/
|   └── Event.ts
└── util/
    └── math.ts

类中保护方法、变量以单个下划线开头，允许子类覆盖（override）和外部调用；
类中私有方法、变量以双下划线开头，不允许类之外调用、覆盖；

对用户暴露的 API 不应以下划线开头；

// Bad
class Base {
  foo;
  protected foo1;  // Bad
  private foo2;

  foo3() {}
  protected foo4() {}  // Bad
  private foo5() {}  // Bad
}

class Thing extends Base {
  // override
  foo3() {
    super.foo4()
    super.foo5(); // Bad
  }
  // override
  protected foo4() {}
  // override
  private foo5() {} // Bad
}

new Thing().foo3();
new Thing().foo4(); // Bad
new Thing().foo5(); // Bad

// Good
class Base {
  foo;
  protected _foo1;
  private __foo2;

  foo3() {}
  protected _foo4() {}
  private __foo5() {}
}

class Thing extends Base {
  // override
  foo3() {
    super._foo4();
  }
  // override
  protected _foo4() {}
}

new Thing().foo3();

对于声明的方法、变量字段注释应以多行注释为主，这样才会在代码提示时附带注释信息

// Bad
class Base {
  // something
  foo;

  // something1
  foo1() {
    let foo2 = 0;

    /** something2 */
    if (foo2) {
    }
  }
}

// Good
class Base {
  /** something */
  foo;

  /**
   * something1
   */
  foo1() {
    let foo2 = 0;

    // something2
    if (foo2) {
    }
  }
}

对于一些场景，请使用一些特殊的注释标记进行标注

// TODO something
// 待解决的问题

// BUG something
// 严重的漏洞问题，应及时修复

// FIXME something
// 潜在存在的问题，但对用户影响较小，可以延后修复

// HACK something
// 为了快速解决问题采取了一些特殊方案，后续需要改进

// XXX something
// 用来标记问题，方便后续查找定位

// [ ] something1
// [x] something2
// [ ] something3
// 对待开发的功能或者待解决的问题列表，并标记进度

使用 VS Code，可以安装 Todo Tree 扩展。

CSS

组件库采用 Less 预处理器语言编写样式（CSS），并采用 CSS Modules 对 CSS 进行封装。

注意：构建产物中仅包含 JS 文件，CSS 样式将打包到 JS 代码中，其它静态资源（图片等）将会以 Data URLs 形式打包到 JS 代码中。

import styles from './index.module.less';
import bgImage from './background.png';
import bgSVGImage from './background.svg';

CSS Modules

CSS Modules 不对所有的样式文件生效，仅对文件名匹配上 /\.module(s)?\./ 的文件生效，而且类名必须以 JS 的方式添加到 DOM 元素上。例如：

import styles from 'index.module.css';

div.classList.add(styles['btn-primary']);

对于未启用 CSS Modules 的样式文件，直接 import 即可，CSS 全局有效，类名声明在 DOM 元素上即可。例如：

import 'index.css';

<div class="btn-primary"></div>;

文档的编写规范

这里主要针对配置项和 APIs 内容的文档编写进行以下约束。

目录（TOC）

当前文档系统的页面右侧会有目录（TOC）用来快速浏览器文档内容和导航，所以我们要借助这个提高文档的检索效率。

当前配置为目录中仅展示二、三级标题，所以将**二级标题定义为文档内容的大分类，三级标题定义为文档内容的小分类和具体配置项及 APIs 名称，且在三级标题为代码相关的内容时，使用 `code` 进行标记并体现出配置项的路径。**示例如下：

文档的标题编写示例
## 配置项

### `tooltip`

### `series.data`

## APIs

### 事件

### `dv:beforeinit`

### Action

### `dvTwoWayTreeExpandAllNode`

### 其它

代码块

涉及到代码块的内容，要**注明语言进行高亮，提高阅读效率，并合理利用文档系统提供的行高亮等功能提高信息表达的效率和准确性。**示例如下：

/path/to/source.ts
function foo() {
  start();
  process();
  end();
}

版本迭代标记

对于组件的版本迭代过程中新增和弃用的内容应在文档中确切的标记号。例如：

v0.2.2+

或

v0.2.2 ~ v0.2.10

或

v0.2.2

文档格式案例

参考 ZRender 和 ECharts 官方文档格式，约定以下文档格式。

配置项

配置项文档格式案例
### `series.data`

[注意事项提示卡片]   // 可选

- [类型]
- [默认值]   // 可选

[版本迭代标记] // 可选

[配置项描述]

[示例代码块]  // 可选

[相关文档链接列表]  // 可选

APIs

APIs 文档格式案例
### `on()`

[注意事项提示卡片]   // 可选

- [函数签名]
- [参数]   // 可选

  | 名称 | 类型     | 是否可选 | 默认值 | 描述 |
  | :--- | :------- | :------- | :----- | :--- |
  | name | `string` | 是       |        |      |

- [返回值]   // 可选

[版本迭代标记] // 可选

[描述]

[示例代码块]  // 可选

[相关文档链接列表]  // 可选

Git 分支管理​

风格指南​

Git 提交信息格式​

JavaScript/TypeScript​

CSS​

CSS Modules​

文档的编写规范​

目录（TOC）​

代码块​

版本迭代标记​

文档格式案例​

配置项​

APIs​