[new feature] Docs: 增加 contribute 指南 (#182)

* add contribute doc

* fix url path

* 文档格式调整

* readme 标题修改

* contribute guide for english

* contribute for english

* add pr & issue guildlines

* change title && add pr & issue in zh_CN.md

* add desc in zh_CN

* add zh-CN markdown
This commit is contained in:
Yao
2017-10-10 14:39:58 +08:00
committed by GitHub
parent fcb9a4a8a9
commit c0ed30e7be
6 changed files with 203 additions and 16 deletions

View File

@@ -0,0 +1,110 @@
# 开发 vant
首先感谢你使用 Vant。
以下是关于向 Vant 提交代码的指南。在向 Vant 提交 Issue 或者 PR 之前,请先花几分钟时间阅读以下文字。
## Issue 规范
如果遇到问题,请先确认这个是否已经在 issue 中有记录或者已被修复。你可以直接搜索已有的 Issue 或者 PR。
提 Issue 时,请用简短的语言描述遇到的问题,并添加出现问题时的环境和复现步骤
## Pull Request 规范
- 在开始大量代码修改之前,建议先开一个 Issue 进行讨论
- 如果遇到问题,建议保持你的 PR 足够小。保证一个 PR 只解决一个问题或只添加一个功能。
- 当新增组件或者修改原有组件时,记得增加或者修改测试代码,保证代码的稳定
- 在提交 PR 之前,请先进行 rebase 操作,保证提交时的 history 是干净的
- 在 PR 中请添加合适的描述,并关联相关的 Issue
## 初始化项目:
```bash
yarn
npm run dev
```
浏览器访问 [http://localhost:8080](http://localhost:8080) 就可以看到所有组件的示例了。
## 代码目录结构
- 仓库的组件代码都位于 `packages` 下,每个组件一个文件夹
- 所有的组件样式代码都位于 `packages/vant-css/src` 下,`vant-css` 也会在发布时单独发包
- `docs/examples-docs` 目录下是文档网站的代码,根据语言划分为 zh-CN 和 en-US本地开发时可以在根目录下运行 `npm run dev` 开启文档网站。
项目目录大致如下:
```
vant
├── build # 组件打包配置和编译需要的脚本
├── docs # 文档网站代码
├── packages # 组件源代码
├── test # 组件测试代码
```
## 添加新组件
主要步骤:
- 添加 Vue 代码
以添加新组件 `Button` 为例,首先在 `packages` 目录下新建目录 `button`,用 `index.js` 或者 `index.vue` 文件做为组件入口,需要的话可以建其他文件来组织代码。
- 添加样式代码
组件对应的样式需要放到 `packages/vant-css/src` 目录下,`Button` 组件的话需要新建一个文件 `button.css`。如若个组件样式比较复杂,为了方便组织代码可以在 `packages/vant-css/src` 下面新建一个同名目录 `button`,里面可以放一些 partial 样式。
新添加的 `button.css` 文件需要在 `packages/vant-css/src/index.css` 中手动 import。
- 添加文档
新组件的文档编写,需要在 `docs/examples-docs` 下各个语言中新建对应同名文档 `button.md`,并在 `docs/src/doc.config.js` 中进行文档路径配置
- 添加测试代码
需要在 `test/unit/specs` 目录下增加对应组件的测试文件,以 .spec.js 结尾,如:`button.spec.js`。测试框架使用了 karma + mocha + sinon + chaivue 相关的操作使用了 [avoriaz](https://github.com/eddyerburgh/avoriaz)
## 组件文档如何编写
`docs/examples-docs` 下根据语言划分了组件文档,每个组件需要在各语言中编辑对应的文档。组件文档采用 markdown 格式,内容包括使用示例以及 `API` 等。具体书写规范请参考 [组件文档书写规范](./markdown.md)。
#### API 说明
组件的 API 说明,请以表格的形式书写,表格包含以下列:
| 参数 | 说明 | 类型 | 默认值 | 备选值 |
| ------------ | ------------- | -------- | ---------- | ----------------- |
| visible | 是否可见 | bool | `false` | `true` \| `false` |
#### Event 说明
组件的 Event 说明,请以表格的形式书写,表格包含以下列:
| 事件名 | 说明 | 参数 |
|-----------|-----------|-----------|
| click | 点击按钮时触发 | event事件对象 |
## 一些实用技巧
#### 组件互相引用
比如说 `Dialog` 里面引用了 `Button` 组件,直接写相对路径引用即可。
#### 组件导出
为了统一管理,每个组件只能通过 `export default` 一个东西,如果需要导出多个变量,请把其余变量挂载在 `export default` 的变量上。
#### 样式
组件样式使用 `precss`,语法请参考 [precss 文档](https://github.com/jonathantneal/precss).
#### 关于 z-index
为了防止 `z-index` 滥用,我们规定了组件库内部的 `z-index` 使用规范。
`z-index` 优先级(从高到低):
* 特殊组件Toast 永远在最上面,[3000, +∞)
* ‘用完就关’ 的组件Dialog, Pop, Actionsheet, image-preview 等 [2000, 3000)
* 其他:组件内部用来控制层次的 z-index 的区间 [-10, 10]尽可能写小一般123这种就够了。

View File

@@ -0,0 +1,47 @@
## 组件文档如何编写
#### 文件格式
组件文档采用 markdown 格式,和普通 markdown 最大的区别是示例代码是直接写在 markdown 文件里面,所以请确保你写的示例代码是可以正确运行的。
#### 文档内的标题规范
文档标题从 `h2`(即 `##` 标题 )开始,每往下一级多加一个 `#` 号;一般到 `h3` (两级标题) 或`h4` (三级标题)即可,不要出现过多的标题层级。
#### 组件描述
大标题下面是对组件的一句话简要描述。
#### 使用指南(可选)
如果组件需要使用指南,放在组件描述下方,另起一个二级标题。
#### 代码演示
另起一个二级标题,正文可以是 markdown 和示例的混合。示例的结构如下:
// 在 demo 端之外放置的 script 会直接运行
// 在 script 中声明的 vue 变量,在 demo 中都可以直接使用
<script>
export default {
data() {
return {
size: 'large'
};
}
};
</script>
:::demo 基础用法(必须以:::demo开头后面的描述可选如果有的话控制在一两句话不要过长
```html // :::demo后面必须接代码段否则不会识别为示例
<van-button :size="size"> // 在内容区直接写 vue 中 template 段代码即可
Large
</van-button>
```
::: // 示例结束的标记,必须接在代码段之后,否则不会识别为示例
代码演示的几个书写原则:
- 从简单用法开始介绍,不要上来就同时使用一大堆 API会让人觉得难以上手
- 正交性原则一个示例只演示一个或者一类API 的使用方法,如无特殊需求不要在一个示例中同时演示多个 API 混合使用
- 如果示例的一句话描述无法完整描述整个场景,可以在 `:::demo` 之前写一段详细的说明性文字