docs: 📝 配置git规范

2026-03-17 17:36:55 +08:00
parent 871cbcb831
commit 0e489da387
16 changed files with 829 additions and 370 deletions
@@ -0,0 +1,234 @@
+# Git 提交规范指南
+
+本项目使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范,通过 `commitizen` + `cz-git` 提供交互式提交体验。
+
+## 快速开始
+
+### 使用交互式提交(推荐)
+
+```bash
+# 1. 暂存你的更改
+git add .
+
+# 2. 使用交互式提交
+pnpm commit
+```
+
+交互式提交会引导你完成:
+1. 选择提交类型(feat/fix/docs 等)
+2. 选择影响范围(common/vue3/uni-app 等,可跳过)
+3. 输入简短描述(必填,4-100 字符)
+4. 输入详细描述(可选)
+5. 是否有破坏性变更(可选)
+6. 关联 Issue(可选)
+
+### 手动提交
+
+如果你熟悉规范,也可以手动提交:
+
+```bash
+git commit -m "feat(common): 添加 debounce 防抖函数"
+```
+
+## 提交信息格式
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type(必填)
+
+| 类型 | Emoji | 说明 | 示例 |
+|------|-------|------|------|
+| `feat` | ✨ | 新功能 | `feat(common): 添加 throttle 节流函数` |
+| `fix` | 🐛 | Bug 修复 | `fix(uni-app): 修复蓝牙连接超时问题` |
+| `docs` | 📚 | 文档更新 | `docs: 更新 README 安装说明` |
+| `style` | 💎 | 代码格式(不影响逻辑) | `style(vue3): 格式化代码缩进` |
+| `refactor` | 📦 | 重构(不是新功能也不是修复) | `refactor(common): 优化 Permission 类实现` |
+| `perf` | 🚀 | 性能优化 | `perf(vue3): 优化 mergeClass 性能` |
+| `test` | 🚨 | 测试相关 | `test(common): 添加 timer 单元测试` |
+| `build` | 🛠 | 构建系统或依赖更新 | `build: 升级 webpack 到 5.80` |
+| `ci` | ⚙️ | CI 配置更新 | `ci: 添加 GitHub Actions 配置` |
+| `chore` | ♻️ | 其他杂项 | `chore: 更新 .gitignore` |
+| `revert` | 🗑 | 回滚之前的提交 | `revert: 回滚 feat(common): xxx` |
+
+### Scope(可选)
+
+影响范围,必须是以下之一:
+
+- `common` - @r-utils/common 包
+- `vue3` - @r-utils/vue3 包
+- `vue2` - @r-utils/vue2 包
+- `uni-app` - @r-utils/uni-app 包
+- `deps` - 依赖更新
+- `release` - 版本发布
+
+如果改动影响多个包或不属于特定包,可以省略 scope。
+
+### Subject(必填)
+
+简短描述,要求:
+- 长度: 4-100 字符
+- 使用祈使句,如"添加"而不是"添加了"
+- 首字母小写
+- 结尾不加句号
+
+### Body(可选)
+
+详细描述,说明:
+- 改动的原因
+- 与之前行为的对比
+- 实现细节
+
+每行不超过 200 字符。
+
+### Footer(可选)
+
+用于:
+- 关联 Issue: `fix #123` 或 `close #456`
+- 说明破坏性变更: `BREAKING CHANGE: xxx`
+
+## 提交示例
+
+### 基础示例
+
+```bash
+# 新功能
+feat(common): 添加 debounce 防抖函数
+
+# Bug 修复
+fix(uni-app): 修复蓝牙连接超时问题
+
+# 文档更新
+docs: 更新安装说明
+
+# 重构
+refactor(vue3): 优化 mergeClass 实现逻辑
+```
+
+### 带 Body 的示例
+
+```bash
+feat(common): 添加 throttle 节流函数
+
+实现了一个通用的节流函数,支持:
+- 自定义延迟时间
+- leading 和 trailing 选项
+- 取消功能
+```
+
+### 关联 Issue 的示例
+
+```bash
+fix(uni-app): 修复蓝牙连接超时问题
+
+修复了在某些 Android 设备上蓝牙连接超时的问题,
+通过增加重试机制和优化超时时间来提高连接成功率。
+
+fix #123
+```
+
+### 破坏性变更示例
+
+```bash
+feat(common)!: 重构 Permission 类 API
+
+BREAKING CHANGE: Permission 类的构造函数参数已更改
+
+之前:
+new Permission('module:action')
+
+现在:
+new Permission({ module: 'module', action: 'action' })
+
+迁移指南请参考文档。
+```
+
+## 提交规则
+
+项目通过 `commitlint` 强制执行以下规则:
+
+1. **type 必须是允许的类型之一**
+2. **scope 如果提供,必须是允许的范围之一**
+3. **subject 不能为空,长度 4-100 字符**
+4. **subject 不能以句号结尾**
+5. **type 和 scope 必须小写**
+6. **header 总长度不超过 120 字符**
+7. **body 和 footer 每行不超过 200 字符**
+
+如果提交信息不符合规范,`commit-msg` hook 会阻止提交并提示错误。
+
+## Git Hooks
+
+项目配置了以下 Git Hooks:
+
+### pre-commit
+
+运行 `lint-staged`,自动检查和修复:
+- ESLint 代码检查
+- Prettier 代码格式化
+- Jest 单元测试
+
+### commit-msg
+
+使用 `commitlint` 校验提交信息格式。
+
+## 常见问题
+
+### Q: 提交被拒绝怎么办?
+
+**A:** 检查以下几点:
+1. 提交信息格式是否正确
+2. 代码是否通过 ESLint 检查
+3. 测试是否全部通过
+
+### Q: 如何跳过 hooks?
+
+**A:** 不建议跳过 hooks,但如果确实需要:
+
+```bash
+git commit --no-verify -m "your message"
+```
+
+### Q: 如何修改上一次提交?
+
+**A:** 使用 `git commit --amend`:
+
+```bash
+# 修改提交信息
+git commit --amend
+
+# 添加遗漏的文件
+git add forgotten-file.js
+git commit --amend --no-edit
+```
+
+### Q: 提交信息写错了怎么办?
+
+**A:** 如果还没有 push,可以修改:
+
+```bash
+# 修改最后一次提交
+git commit --amend
+
+# 修改更早的提交(交互式 rebase)
+git rebase -i HEAD~3
+```
+
+如果已经 push,不建议修改,可以创建新的提交来修正。
+
+## 参考资料
+
+- [Conventional Commits 规范](https://www.conventionalcommits.org/)
+- [cz-git 文档](https://cz-git.qbb.sh/)
+- [commitlint 文档](https://commitlint.js.org/)
+- [Angular 提交规范](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
+
+## 相关文档
+
+- [贡献指南](./CONTRIBUTING.md)
+- [Pull Request 模板](../.github/PULL_REQUEST_TEMPLATE.md)
@@ -0,0 +1,220 @@
+# 贡献指南
+
+感谢你对 `@r-utils` 项目的关注!本文档将帮助你了解如何参与项目贡献。
+
+## 开发环境要求
+
+- Node.js >= 18.12.0
+- pnpm 8.15.6
+
+## 快速开始
+
+### 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
+# 构建所有包
+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 进行代码检查和格式化
+- 遵循项目的 `.eslintrc` 配置
+- 提交前运行 `pnpm lint` 和 `pnpm format`
+
+### 测试
+
+- 为新功能编写单元测试
+- 确保所有测试通过: `pnpm test`
+- 测试文件放在各包的 `test/` 目录下
+- 使用 Jest 作为测试框架
+
+### 文档
+
+- 为新功能添加 JSDoc 注释
+- 更新相关的 README 文档
+- 如果是重大变更,更新 CHANGELOG
+
+## Monorepo 结构
+
+```
+r-util-js/
+├── packages/
+│   ├── common/      # 通用工具库
+│   ├── vue3/        # Vue3 工具
+│   ├── vue2/        # Vue2 工具
+│   └── uni-app/     # uni-app 工具
+├── scripts/         # 构建和发布脚本
+└── docs/            # 文档
+```
+
+## 发布流程
+
+发布由维护者负责,使用 `standard-version` 自动生成版本号和 CHANGELOG:
+
+```bash
+# 生成版本和 CHANGELOG
+pnpm release
+
+# 发布到 npm
+pnpm publish -r
+```
+
+## 需要帮助?
+
+- 查看 [README.md](../README.md) 了解项目概况
+- 查看 [CLAUDE.md](../CLAUDE.md) 了解项目架构
+- 在 [Issues](https://gitee.com/codice_fabbrica/r-util-js/issues) 提问或报告 Bug
+- 联系维护者: randy1924@163.com
+
+## 行为准则
+
+- 尊重所有贡献者
+- 提供建设性的反馈
+- 专注于对项目最有利的事情
+- 保持友好和专业的态度
+
+感谢你的贡献! 🎉