235 lines
5.2 KiB
Markdown
235 lines
5.2 KiB
Markdown
|
# 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)
|