diff --git a/packages/vant/docs/markdown/contribution.en-US.md b/packages/vant/docs/markdown/contribution.en-US.md new file mode 100644 index 000000000..f49e954e6 --- /dev/null +++ b/packages/vant/docs/markdown/contribution.en-US.md @@ -0,0 +1,141 @@ +# Contribution Guide + +### Introduction + +Thank you for using Vant. + +Below are the guidelines for submitting feedback or code to Vant. Please take a few minutes to read the following before submitting an issue or PR to Vant. + +### Issue Specification + +- If you encountered a problem, please first confirm whether the problem has been recorded in the issue or has been fixed. +- When submitting an issue, please describe the problem you encountered in a short language, and add the environment and reproduction steps when the problem occurs. + +## Participate in development + +### Local development + +Before developing locally, please make sure that [Node.js >= 14.19.0](https://nodejs.org) is installed in your development environment. + +Follow the steps below to develop Vant components locally. + +```bash +# Clone repository +git clone git@github.com:vant-ui/vant.git + +# Enable pnpm package manager +corepack enable + +# If you can't use corepack, you can also install pnpm manually +npm install -g pnpm@7 + +# Install dependencies +pnpm i + +# Start development +pnpm dev +``` + +Different branches of the repository correspond to different Vant versions, please switch to the appropriate branch for development: + +- The main branch corresponds to the Vant 4 version, suitable for Vue 3 +- 3.x branch corresponds to Vant 3 version, suitable for Vue 3 +- 2.x branch corresponds to Vant 2 version, suitable for Vue 2 + +### Mirror repository + +If GitHub cloning is slow, you can also directly clone Vant's [mirror repository](https://gitee.com/vant-contrib/vant) directly on gitee: + +```bash +git clone git@gitee.com:vant-contrib/vant.git +``` + +The mirror repository is only used to speed up local access, please do not submit issues and pull requests to the mirror repository. + +### Directory Structure + +Vant uses monorepo for code management, and all subpackages are in the `packages/vant` directory: + +``` +root +└─ packages + ├─ vant # Component library + ├─ vant-cli # Scaffolding + ├─ vant-icons # Icon library + ├─ vant-use # Composition API + └─ .... # Other npm packages +``` + +Among them, the `packages/vant` directory is the core code of the component library: + +``` +vant +├─ docs # Documentation +├─ src # Component source code +├─ test # Test utils +└─ vant.config.mjs # Document configuration +``` + +The `packages/vant/src` directory contains the source code of each component, and each folder corresponds to a component: + +``` +src +└─ button + ├─ demo # Demo code + ├─ test # Unit test + ├─ Component.tsx # Component + ├─ index.ts # Component entry + ├─ index.less # Styles + ├─ README.md # English document + └─ README.zh-CN.md # Chinese document +``` + +### Code Specification + +When writing code, please note: + +- Make sure the code can pass the repository's ESLint check. +- Make sure the code format is standardized, use prettier for code formatting. +- Make sure you don't use incompatible APIs like `async`, `await`. + +## Submitting a Pull Request + +### Reference Guide + +If this is your first time submitting a pull request on GitHub, you can learn from the following article: + +- [First participation in open source](https://github.com/firstcontributions/first-contributions) + +### Pull Request Specification + +When submitting a Pull Request, please note: + +- Keep your PRs small enough that a PR only addresses a single issue or adds a single feature. +- When adding new components or modifying original components, remember to add or modify the corresponding unit tests to ensure the stability of the code. +- Please include an appropriate description in the PR, and link related issues. + +### Pull Request Process + +1. Fork the main repository. If you have already forked, please synchronize the latest code from the main repository. +2. Create a new branch based on the main branch of the repository after the fork, such as `feature/button_color`. +3. Develop on the new branch. When development is complete, submit a pull request to the main branch of the main repository. +4. The pull request is merged into the main repository after the review is approved. +5. Wait for Vant to release a new version, usually once a week. + +### Synchronize the latest code + +Before submitting a Pull Request, please synchronize the latest code of the main repository according to the following process: + +```bash +# Add the main repository to remote +git remote add upstream git@github.com:vant-ui/vant.git + +# Pull the latest code from the main repository +git fetch upstream + +# Switch to the main branch +git checkout main + +# Merge the code from the main repository +git merge upstream/main +``` diff --git a/packages/vant/docs/markdown/contribution.zh-CN.md b/packages/vant/docs/markdown/contribution.zh-CN.md index 933630016..cb7aa2396 100644 --- a/packages/vant/docs/markdown/contribution.zh-CN.md +++ b/packages/vant/docs/markdown/contribution.zh-CN.md @@ -66,7 +66,7 @@ root └─ .... # 其他周边 npm 包 ``` -其中,`vant` 目录为组件库的核心代码: +其中,`packages/vant` 目录为组件库的核心代码: ``` vant @@ -76,7 +76,7 @@ vant └─ vant.config.mjs # 文档网站配置 ``` -`src` 目录包含各个组件的源码,每个文件夹对应一个组件: +`packages/vant/src` 目录包含各个组件的源码,每个文件夹对应一个组件: ``` src @@ -86,7 +86,6 @@ src ├─ Component.tsx # 组件 ├─ index.ts # 组件入口 ├─ index.less # 样式 - ├─ var.less # 样式变量 ├─ README.md # 英文文档 └─ README.zh-CN.md # 中文文档 ``` @@ -97,22 +96,22 @@ src - 确保代码可以通过仓库的 ESLint 校验。 - 确保代码格式是规范的,使用 prettier 进行代码格式化。 -- 确保没有使用超出兼容性范围的 API,比如 `async/await`。 +- 确保没有使用超出兼容性范围的 API,比如 `async`, `await`. -## 提交 PR +## 提交 Pull Request ### 参考指南 如果你是第一次在 GitHub 上提 Pull Request ,可以阅读下面这两篇文章来学习: -- [如何优雅地在 GitHub 上贡献代码](https://segmentfault.com/a/1190000000736629) - [第一次参与开源](https://github.com/firstcontributions/first-contributions/blob/main/translations/README.zh-cn.md) +- [如何优雅地在 GitHub 上贡献代码](https://segmentfault.com/a/1190000000736629) ### Pull Request 规范 在提交 Pull Request 时,请注意: -- 如果遇到问题,建议保持你的 PR 足够小。保证一个 PR 只解决单个问题、添加单个功能。 +- 保持你的 PR 足够小,一个 PR 只解决单个问题或添加单个功能。 - 当新增组件或者修改原有组件时,记得增加或者修改对应的单元测试,保证代码的稳定。 - 在 PR 中请添加合适的描述,并关联相关的 Issue。 @@ -129,7 +128,7 @@ src 提 Pull Request 前,请依照下面的流程同步主仓库的最新代码: ```bash -# 添加主仓库到 remote,作为 fork 后仓库的上游仓库 +# 添加主仓库到 remote git remote add upstream git@github.com:vant-ui/vant.git # 拉取主仓库最新代码 diff --git a/packages/vant/vant.config.mjs b/packages/vant/vant.config.mjs index ef9ac5e92..a7cb150c5 100644 --- a/packages/vant/vant.config.mjs +++ b/packages/vant/vant.config.mjs @@ -523,6 +523,10 @@ location.href = location.href.replace('youzan.github.io', 'vant-ui.github.io'); path: 'migrate-from-v3', title: 'Upgrade from v3 to v4', }, + { + path: 'contribution', + title: 'Contribution Guide', + }, { path: 'design', title: 'Design Resources',