2026-03-17 17:36:55 +08:00
|
|
|
|
# 贡献指南
|
|
|
|
|
|
|
|
|
|
|
|
感谢你对 `@r-utils` 项目的关注!本文档将帮助你了解如何参与项目贡献。
|
|
|
|
|
|
|
|
|
|
|
|
## 开发环境要求
|
|
|
|
|
|
|
|
|
|
|
|
- Node.js >= 18.12.0
|
2026-05-28 11:30:35 +08:00
|
|
|
|
- pnpm >= 10.0.0
|
2026-03-17 17:36:55 +08:00
|
|
|
|
|
|
|
|
|
|
## 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
### 1. Fork 并克隆仓库
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 克隆你 fork 的仓库
|
|
|
|
|
|
git clone https://gitee.com/your-username/r-util-js.git
|
|
|
|
|
|
cd r-util-js
|
|
|
|
|
|
|
|
|
|
|
|
# 安装依赖
|
|
|
|
|
|
pnpm install
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 2. 创建分支
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 从 master 分支创建新分支
|
|
|
|
|
|
git checkout -b feat/your-feature-name
|
|
|
|
|
|
# 或
|
|
|
|
|
|
git checkout -b fix/your-bug-fix
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
分支命名规范:
|
|
|
|
|
|
- `feat/xxx` - 新功能
|
|
|
|
|
|
- `fix/xxx` - Bug 修复
|
|
|
|
|
|
- `docs/xxx` - 文档更新
|
|
|
|
|
|
- `refactor/xxx` - 代码重构
|
|
|
|
|
|
- `test/xxx` - 测试相关
|
|
|
|
|
|
- `chore/xxx` - 构建/工具相关
|
|
|
|
|
|
|
|
|
|
|
|
### 3. 开发与测试
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-05-28 11:30:35 +08:00
|
|
|
|
# 构建所有包（Turbo）
|
2026-03-17 17:36:55 +08:00
|
|
|
|
pnpm build
|
|
|
|
|
|
|
|
|
|
|
|
# 运行测试
|
|
|
|
|
|
pnpm test
|
|
|
|
|
|
|
|
|
|
|
|
# 代码检查
|
|
|
|
|
|
pnpm lint
|
|
|
|
|
|
|
|
|
|
|
|
# 代码格式化
|
|
|
|
|
|
pnpm format
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 4. 提交代码
|
|
|
|
|
|
|
|
|
|
|
|
本项目使用 **Conventional Commits** 规范,并通过 `commitizen` + `cz-git` 提供交互式提交体验。
|
|
|
|
|
|
|
|
|
|
|
|
#### 使用交互式提交(推荐)
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 暂存你的更改
|
|
|
|
|
|
git add .
|
|
|
|
|
|
|
|
|
|
|
|
# 使用交互式提交
|
|
|
|
|
|
pnpm commit
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
交互式提交会引导你完成以下步骤:
|
|
|
|
|
|
1. **选择提交类型** - feat/fix/docs 等
|
|
|
|
|
|
2. **输入影响范围** - 可选,如 common/vue3/uni-app
|
|
|
|
|
|
3. **输入简短描述** - 必填,简明扼要说明改动
|
|
|
|
|
|
4. **输入详细描述** - 可选,提供更多上下文
|
|
|
|
|
|
5. **是否有破坏性变更** - 如果有,需要详细说明
|
|
|
|
|
|
6. **关联 Issue** - 可选,如 `fix #123`
|
|
|
|
|
|
|
|
|
|
|
|
#### 手动提交
|
|
|
|
|
|
|
|
|
|
|
|
如果你熟悉规范,也可以手动提交:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
git commit -m "feat(common): 添加新的工具函数"
|
|
|
|
|
|
git commit -m "fix(vue3): 修复 mergeClass 类型错误"
|
|
|
|
|
|
git commit -m "docs: 更新 README 文档"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### 提交信息格式
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
<type>(<scope>): <subject>
|
|
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
|
|
<footer>
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**Type 类型:**
|
|
|
|
|
|
- `feat` ✨ - 新功能
|
|
|
|
|
|
- `fix` 🐛 - Bug 修复
|
|
|
|
|
|
- `docs` 📚 - 文档更新
|
|
|
|
|
|
- `style` 💎 - 代码格式(不影响代码逻辑)
|
|
|
|
|
|
- `refactor` 📦 - 重构(既不是新功能也不是修复)
|
|
|
|
|
|
- `perf` 🚀 - 性能优化
|
|
|
|
|
|
- `test` 🚨 - 测试相关
|
|
|
|
|
|
- `build` 🛠 - 构建系统或依赖更新
|
|
|
|
|
|
- `ci` ⚙️ - CI 配置更新
|
|
|
|
|
|
- `chore` ♻️ - 其他杂项(构建流程、依赖管理等)
|
|
|
|
|
|
- `revert` 🗑 - 回滚之前的提交
|
|
|
|
|
|
|
|
|
|
|
|
**Scope 范围(可选):**
|
|
|
|
|
|
- `common` - @r-utils/common 包
|
|
|
|
|
|
- `vue3` - @r-utils/vue3 包
|
|
|
|
|
|
- `vue2` - @r-utils/vue2 包
|
|
|
|
|
|
- `uni-app` - @r-utils/uni-app 包
|
|
|
|
|
|
- 或具体的文件/模块名
|
|
|
|
|
|
|
|
|
|
|
|
**Subject 主题:**
|
|
|
|
|
|
- 简短描述(建议 50 字符以内)
|
|
|
|
|
|
- 使用祈使句,如"添加"而不是"添加了"
|
|
|
|
|
|
- 首字母小写
|
|
|
|
|
|
- 结尾不加句号
|
|
|
|
|
|
|
|
|
|
|
|
**示例:**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 好的提交信息
|
|
|
|
|
|
feat(common): 添加 debounce 防抖函数
|
|
|
|
|
|
fix(uni-app): 修复蓝牙连接超时问题
|
|
|
|
|
|
docs: 更新安装说明
|
|
|
|
|
|
refactor(vue3): 优化 mergeClass 实现逻辑
|
|
|
|
|
|
|
|
|
|
|
|
# 不好的提交信息
|
|
|
|
|
|
update code
|
|
|
|
|
|
fix bug
|
|
|
|
|
|
修改了一些文件
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 5. 推送并创建 Pull Request
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 推送到你的 fork 仓库
|
|
|
|
|
|
git push origin feat/your-feature-name
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
然后在 Gitee 上创建 Pull Request,请参考 [PR 模板](.gitee/PULL_REQUEST_TEMPLATE.md)填写相关信息。
|
|
|
|
|
|
|
|
|
|
|
|
## Git Hooks
|
|
|
|
|
|
|
|
|
|
|
|
项目配置了以下 Git Hooks(通过 husky):
|
|
|
|
|
|
|
|
|
|
|
|
- **pre-commit** - 运行 `lint-staged` 检查代码格式和 lint
|
|
|
|
|
|
- **commit-msg** - 使用 `commitlint` 校验提交信息格式
|
|
|
|
|
|
|
|
|
|
|
|
如果提交被拒绝,请检查:
|
|
|
|
|
|
1. 代码是否通过 ESLint 检查
|
|
|
|
|
|
2. 提交信息是否符合规范
|
|
|
|
|
|
3. 测试是否全部通过
|
|
|
|
|
|
|
|
|
|
|
|
## 代码规范
|
|
|
|
|
|
|
|
|
|
|
|
### JavaScript/TypeScript
|
|
|
|
|
|
|
|
|
|
|
|
- 使用 ESLint + Prettier 进行代码检查和格式化
|
2026-05-28 11:30:35 +08:00
|
|
|
|
- 遵循项目的 `eslint.config.js`（ESLint Flat Config）
|
2026-03-17 17:36:55 +08:00
|
|
|
|
- 提交前运行 `pnpm lint` 和 `pnpm format`
|
|
|
|
|
|
|
|
|
|
|
|
### 测试
|
|
|
|
|
|
|
|
|
|
|
|
- 为新功能编写单元测试
|
|
|
|
|
|
- 确保所有测试通过: `pnpm test`
|
|
|
|
|
|
- 测试文件放在各包的 `test/` 目录下
|
2026-05-28 11:30:35 +08:00
|
|
|
|
- 使用 Vitest 作为测试框架
|
2026-03-17 17:36:55 +08:00
|
|
|
|
|
|
|
|
|
|
### 文档
|
|
|
|
|
|
|
|
|
|
|
|
- 为新功能添加 JSDoc 注释
|
|
|
|
|
|
- 更新相关的 README 文档
|
|
|
|
|
|
- 如果是重大变更,更新 CHANGELOG
|
|
|
|
|
|
|
|
|
|
|
|
## Monorepo 结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
r-util-js/
|
|
|
|
|
|
├── packages/
|
|
|
|
|
|
│ ├── common/ # 通用工具库
|
|
|
|
|
|
│ ├── vue3/ # Vue3 工具
|
|
|
|
|
|
│ ├── vue2/ # Vue2 工具
|
|
|
|
|
|
│ └── uni-app/ # uni-app 工具
|
|
|
|
|
|
└── docs/ # 文档
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 发布流程
|
|
|
|
|
|
|
2026-05-28 11:30:35 +08:00
|
|
|
|
发布由维护者负责，详细流程请查看 [发布流程文档](./RELEASE.md)。
|
|
|
|
|
|
|
|
|
|
|
|
常用命令：
|
2026-03-17 17:36:55 +08:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-05-28 11:30:35 +08:00
|
|
|
|
pnpm changeset
|
|
|
|
|
|
pnpm release:check
|
2026-03-17 17:36:55 +08:00
|
|
|
|
pnpm release
|
2026-05-28 11:30:35 +08:00
|
|
|
|
pnpm release:publish
|
2026-03-17 17:36:55 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 需要帮助?
|
|
|
|
|
|
|
|
|
|
|
|
- 查看 [README.md](../README.md) 了解项目概况
|
|
|
|
|
|
- 查看 [CLAUDE.md](../CLAUDE.md) 了解项目架构
|
|
|
|
|
|
- 在 [Issues](https://gitee.com/codice_fabbrica/r-util-js/issues) 提问或报告 Bug
|
|
|
|
|
|
- 联系维护者: randy1924@163.com
|
|
|
|
|
|
|
|
|
|
|
|
## 行为准则
|
|
|
|
|
|
|
|
|
|
|
|
- 尊重所有贡献者
|
|
|
|
|
|
- 提供建设性的反馈
|
|
|
|
|
|
- 专注于对项目最有利的事情
|
|
|
|
|
|
- 保持友好和专业的态度
|
|
|
|
|
|
|
|
|
|
|
|
感谢你的贡献! 🎉
|
