Vant4 貢獻(xiàn)指南

介紹

感謝你使用 Vant。

以下是關(guān)于向 Vant 提交反饋或代碼的指南。在向 Vant 提交 issue 或者 PR 之前，請先花幾分鐘時間閱讀以下內(nèi)容。

Issue 規(guī)范

• 遇到問題時，請先確認(rèn)這個問題是否已經(jīng)在 issue 中有記錄或者已被修復(fù)。
• 提 issue 時，請用簡短的語言描述遇到的問題，并添加出現(xiàn)問題時的環(huán)境和復(fù)現(xiàn)步驟。

參與開發(fā)

本地開發(fā)

在進(jìn)行本地開發(fā)前，請先確保你的開發(fā)環(huán)境中安裝了 Node.js >= 14.19.0。

按照下面的步驟操作，即可在本地開發(fā) Vant 組件。

# 克隆倉庫
git clone git@github.com:vant-ui/vant.git

# 啟用 pnpm 包管理器
corepack enable

# 如果無法使用 corepack，你也可以手動安裝 pnpm
npm install -g pnpm@7

# 安裝依賴
pnpm i

# 進(jìn)入開發(fā)模式，瀏覽器訪問 localhost
pnpm dev

倉庫的不同分支對應(yīng)不同的 Vant 版本，請切換到對應(yīng)分支進(jìn)行開發(fā)：

• dev 分支對應(yīng) Vant 4 版本，適用于 Vue 3
• 3.x 分支對應(yīng) Vant 3 版本 ，適用于 Vue 3
• 2.x 分支對應(yīng) Vant 2 版本，適用于 Vue 2

鏡像倉庫

如果 GitHub 克隆速度較慢，你也可以直接克隆 Vant 在 gitee 上的鏡像倉庫：

git clone git@gitee.com:vant-contrib/vant.git

鏡像倉庫僅用于加快國內(nèi)的訪問速度，請勿在鏡像倉庫中提 issue 和 Pull Request。

目錄結(jié)構(gòu)

Vant 采用 monorepo 進(jìn)行代碼管理，所有子包在 ?packages? 目錄下:

root
└─ packages
   ├─ vant        # 組件庫
   ├─ vant-cli    # 腳手架
   ├─ vant-icons  # 圖標(biāo)庫
   ├─ vant-use    # Composition API
   └─ ....        # 其他周邊 npm 包

其中，?vant? 目錄為組件庫的核心代碼：

vant
├─ docs             # 文檔
├─ src              # 組件源代碼
├─ test             # 單測工具類
└─ vant.config.mjs  # 文檔網(wǎng)站配置

?src? 目錄包含各個組件的源碼，每個文件夾對應(yīng)一個組件：

src
└─ button
   ├─ demo             # 示例代碼
   ├─ test             # 單元測試
   ├─ Component.tsx    # 組件
   ├─ index.ts         # 組件入口
   ├─ index.less       # 樣式
   ├─ var.less         # 樣式變量
   ├─ README.md        # 英文文檔
   └─ README.zh-CN.md  # 中文文檔

代碼規(guī)范

在編寫代碼時，請注意：

• 確保代碼可以通過倉庫的 ESLint 校驗。
• 確保代碼格式是規(guī)范的，使用 prettier 進(jìn)行代碼格式化。
• 確保沒有使用超出兼容性范圍的 API，比如 ?async/await?。

提交 PR

參考指南

如果你是第一次在 GitHub 上提 Pull Request ，可以閱讀下面這兩篇文章來學(xué)習(xí)：

• 如何優(yōu)雅地在 GitHub 上貢獻(xiàn)代碼
• 第一次參與開源

Pull Request 規(guī)范

在提交 Pull Request 時，請注意：

• 如果遇到問題，建議保持你的 PR 足夠小。保證一個 PR 只解決單個問題、添加單個功能。
• 當(dāng)新增組件或者修改原有組件時，記得增加或者修改對應(yīng)的單元測試，保證代碼的穩(wěn)定。
• 在 PR 中請?zhí)砑雍线m的描述，并關(guān)聯(lián)相關(guān)的 Issue。

Pull Request 流程

1. fork 主倉庫，如果已經(jīng) fork 過，請同步主倉庫的最新代碼。
2. 基于 fork 后倉庫的 dev 分支新建一個分支，比如 feature/button_color。
3. 在新分支上進(jìn)行開發(fā)，開發(fā)完成后，提 Pull Request 到主倉庫的 dev 分支。
4. Pull Request 會在 Review 通過后被合并到主倉庫。
5. 等待 Vant 發(fā)布新版本，一般是每周一次。

同步最新代碼

提 Pull Request 前，請依照下面的流程同步主倉庫的最新代碼：

# 添加主倉庫到 remote，作為 fork 后倉庫的上游倉庫
git remote add upstream git@github.com:vant-ui/vant.git

# 拉取主倉庫最新代碼
git fetch upstream

# 切換至 dev 分支
git checkout dev

# 合并主倉庫代碼
git merge upstream/dev