221 lines
4.7 KiB
Markdown
221 lines
4.7 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 `@r-utils` 项目的关注!本文档将帮助你了解如何参与项目贡献。
|
||
|
||
## 开发环境要求
|
||
|
||
- Node.js >= 18.12.0
|
||
- pnpm >= 10.0.0
|
||
|
||
## 快速开始
|
||
|
||
### 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
|
||
# 构建所有包（Turbo）
|
||
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 进行代码检查和格式化
|
||
- 遵循项目的 `eslint.config.js`（ESLint Flat Config）
|
||
- 提交前运行 `pnpm lint` 和 `pnpm format`
|
||
|
||
### 测试
|
||
|
||
- 为新功能编写单元测试
|
||
- 确保所有测试通过: `pnpm test`
|
||
- 测试文件放在各包的 `test/` 目录下
|
||
- 使用 Vitest 作为测试框架
|
||
|
||
### 文档
|
||
|
||
- 为新功能添加 JSDoc 注释
|
||
- 更新相关的 README 文档
|
||
- 如果是重大变更,更新 CHANGELOG
|
||
|
||
## Monorepo 结构
|
||
|
||
```
|
||
r-util-js/
|
||
├── packages/
|
||
│ ├── common/ # 通用工具库
|
||
│ ├── vue3/ # Vue3 工具
|
||
│ ├── vue2/ # Vue2 工具
|
||
│ └── uni-app/ # uni-app 工具
|
||
└── docs/ # 文档
|
||
```
|
||
|
||
## 发布流程
|
||
|
||
发布由维护者负责，详细流程请查看 [发布流程文档](./RELEASE.md)。
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
pnpm changeset
|
||
pnpm release:check
|
||
pnpm release
|
||
pnpm release:publish
|
||
```
|
||
|
||
## 需要帮助?
|
||
|
||
- 查看 [README.md](../README.md) 了解项目概况
|
||
- 查看 [CLAUDE.md](../CLAUDE.md) 了解项目架构
|
||
- 在 [Issues](https://gitee.com/codice_fabbrica/r-util-js/issues) 提问或报告 Bug
|
||
- 联系维护者: randy1924@163.com
|
||
|
||
## 行为准则
|
||
|
||
- 尊重所有贡献者
|
||
- 提供建设性的反馈
|
||
- 专注于对项目最有利的事情
|
||
- 保持友好和专业的态度
|
||
|
||
感谢你的贡献! 🎉
|