mirror of
https://gitee.com/vant-contrib/vant.git
synced 2025-04-05 19:41:42 +08:00
[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
GitHub
parent
fcb9a4a8a9
commit
c0ed30e7be
10
README.md
10
README.md
@ -55,15 +55,9 @@ import 'vant/lib/vant-css/index.css';
|
||||
Vue.use(vant);
|
||||
```
|
||||
|
||||
## Development
|
||||
## How to contribute
|
||||
|
||||
Start development mode:
|
||||
|
||||
```shell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Visit [http://localhost:8080](http://localhost:8080) to see an example of all components.
|
||||
Please make sure to read the [Contributing Guide](./docs/examples-docs/en-US/contribute.md) before making a pull request.
|
||||
|
||||
## Preview
|
||||
|
||||
|
||||
@ -53,15 +53,11 @@ import 'vant/lib/vant-css/index.css';
|
||||
Vue.use(vant);
|
||||
```
|
||||
|
||||
## 三、开发
|
||||
## 三、贡献代码
|
||||
|
||||
在`docs/src/doc.config.js`文件里合适的地方写入组件声明，根据组件类型（JS组件，CSS组件，Form等）进行区分，在`docs/examples-docs`目录里新建同名的 md 文件，如`waterfall.md`，在项目的根目录下执行以下命令，启动 server：
|
||||
修改代码请阅读我们的 [开发指南](./docs/examples-docs/zh-CN/contribute.md)。
|
||||
|
||||
```shell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
浏览器访问[http://localhost:8080](http://localhost:8080)就可以看到所有组件的示例了。
|
||||
使用过程中发现任何问题都可以提 [Issue](https://github.com/youzan/vant/issues) 给我们，当然，我们也非常欢迎你给我们发 [PR](https://github.com/youzan/vant/pulls)。
|
||||
|
||||
## 四、手机预览
|
||||
|
||||
|
||||
41
docs/examples-docs/en-US/contribute.md
Normal file
41
docs/examples-docs/en-US/contribute.md
Normal file
@ -0,0 +1,41 @@
|
||||
# Contributing to Vant
|
||||
|
||||
The following is a set of guidelines for contributing to Vant. Please spend several minutes in reading these guidelines before you create an issue or pull request.
|
||||
|
||||
Anyway, these are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.
|
||||
|
||||
## Opening an Issue
|
||||
If you think you have found a bug, or have a new feature idea, please start by making sure it hasn't already been reported or fixed. You can search through existing issues and PRs to see if someone has reported one similar to yours.
|
||||
|
||||
Next, create a new issue that briefly explains the problem, and provides a bit of background as to the circumstances that triggered it, and steps to reproduce it.
|
||||
|
||||
## Submitting a Pull Request
|
||||
It's welcomed to pull request, And there are some tips about that:
|
||||
|
||||
- Before working on a large change, it is best to open an issue first to discuss it with the maintainers.
|
||||
|
||||
- When in doubt, keep your pull requests small. To give a PR the best chance of getting accepted, don't bundle more than one feature or bug fix per pull request. It's always best to create two smaller PRs than one big one.
|
||||
|
||||
- When adding new features or modifying existing, please attempt to include tests to confirm the new behaviour.
|
||||
|
||||
- Rebase before creating a PR to keep commit history clear.
|
||||
|
||||
- Add some descriptions and refer relative issues for you PR.
|
||||
|
||||
## Getting started
|
||||
|
||||
```bash
|
||||
git clone git@github.com:youzan/vant.git
|
||||
|
||||
yarn
|
||||
|
||||
npm run dev
|
||||
|
||||
# open http://localhost:8080
|
||||
```
|
||||
|
||||
## Component Developing Guidelines
|
||||
- Create new directory under `packages` for a new component.
|
||||
- All the style code are located under `packages/vant-css/src`.
|
||||
- Refer to `Sku` for nested components.
|
||||
- Refer to `Button` for components that depend on other components.
|
||||
110
docs/examples-docs/zh-CN/contribute.md
Normal file
110
docs/examples-docs/zh-CN/contribute.md
Normal 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 + chai，vue 相关的操作使用了 [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]，尽可能写小，一般1，2，3这种就够了。
|
||||
47
docs/examples-docs/zh-CN/markdown.md
Normal file
47
docs/examples-docs/zh-CN/markdown.md
Normal 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` 之前写一段详细的说明性文字
|
||||
@ -32,7 +32,6 @@
|
||||
&__items {
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
position: relative;
|
||||
height: 100%;
|
||||
}
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user