193 lines
4.3 KiB
Markdown
193 lines
4.3 KiB
Markdown
# Git提交规范
|
||
|
||
## 概述
|
||
|
||
使用 Conventional Commits 规范管理提交信息，确保提交历史清晰可读，便于自动生成变更日志和语义化版本管理。
|
||
|
||
:::tip Conventional Commits 格式
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
:::
|
||
|
||
## 提交类型（type）
|
||
|
||
| 类型 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `feat` | 新功能 | `feat(user): 添加用户导入功能` |
|
||
| `fix` | 修复 bug | `fix(auth): 修复 token 过期后未刷新的问题` |
|
||
| `docs` | 文档变更 | `docs: 更新部署文档` |
|
||
| `style` | 代码格式（不影响逻辑） | `style: 格式化代码缩进` |
|
||
| `refactor` | 重构（非新功能非修复） | `refactor(repo): 统一查询方法封装` |
|
||
| `perf` | 性能优化 | `perf(query): 优化分页查询性能` |
|
||
| `test` | 测试相关 | `test(unit): 添加岗位模块单元测试` |
|
||
| `chore` | 构建/工具变更 | `chore: 更新依赖版本` |
|
||
| `ci` | CI/CD 变更 | `ci: 添加 GitHub Actions 配置` |
|
||
| `revert` | 回滚提交 | `revert: 回滚 feat(user) 提交` |
|
||
|
||
## 范围（scope）
|
||
|
||
可选，用于说明影响的模块或组件：
|
||
|
||
```
|
||
feat(user): 用户模块
|
||
fix(auth): 认证模块
|
||
refactor(repo): Repository 层
|
||
feat(api): API 层
|
||
docs(deploy): 部署文档
|
||
```
|
||
|
||
## 提交信息示例
|
||
|
||
### 简单提交
|
||
|
||
```
|
||
feat(position): 添加岗位状态切换接口
|
||
fix(captcha): 修复验证码过期时间计算错误
|
||
docs: 更新 README 安装说明
|
||
```
|
||
|
||
### 带正文的提交
|
||
|
||
```
|
||
fix(auth): 修复 token 刷新后旧 token 仍有效的问题
|
||
|
||
旧 token 在刷新后未加入黑名单，导致短时间内可同时使用新旧两个 token。
|
||
修复方案：刷新时将旧 token 加入 Redis 黑名单。
|
||
|
||
Closes #123
|
||
```
|
||
|
||
### 破坏性变更
|
||
|
||
```
|
||
feat(api)!: 统一响应格式，移除 data.code 字段
|
||
|
||
BREAKING CHANGE: 响应格式从 {data: {code, data}} 变为 {code, data, msg, ok}
|
||
前端需同步更新响应处理逻辑。
|
||
```
|
||
|
||
:::warning 破坏性变更
|
||
破坏性变更使用 `!` 后缀标记，并在正文或 footer 中说明 `BREAKING CHANGE`。此类变更需在版本号中体现（主版本号 +1）。
|
||
:::
|
||
|
||
## 分支策略
|
||
|
||
| 分支 | 用途 | 命名格式 | 说明 |
|
||
|------|------|---------|------|
|
||
| `main` | 主分支（生产） | `main` | 始终保持可发布状态 |
|
||
| `master` | 开发主分支 | `master` | 日常开发合并目标 |
|
||
| `feature/*` | 功能分支 | `feature/功能名` | 从 master 拉取 |
|
||
| `fix/*` | 修复分支 | `fix/问题描述` | 从 master 拉取 |
|
||
| `hotfix/*` | 紧急修复 | `hotfix/问题描述` | 从 main 拉取 |
|
||
|
||
### 分支工作流
|
||
|
||
```
|
||
1. 从 master 创建功能分支
|
||
git checkout -b feature/position-import master
|
||
|
||
2. 开发完成后提交
|
||
git commit -m "feat(position): 添加岗位 Excel 导入功能"
|
||
|
||
3. 合并到 master
|
||
git checkout master
|
||
git merge feature/position-import
|
||
|
||
4. 推送到远程
|
||
git push origin master
|
||
|
||
5. 生产发布时合并到 main
|
||
git checkout main
|
||
git merge master
|
||
git tag v1.2.0
|
||
```
|
||
|
||
## 版本标签
|
||
|
||
使用语义化版本号（Semantic Versioning）：
|
||
|
||
```
|
||
v主版本号.次版本号.修订号
|
||
v1.2.3
|
||
|
||
主版本号：破坏性变更
|
||
次版本号：新功能（向后兼容）
|
||
修订号：Bug 修复
|
||
```
|
||
|
||
```bash
|
||
# 创建标签
|
||
git tag -a v1.2.0 -m "feat: 添加岗位导入功能"
|
||
|
||
# 推送标签
|
||
git push origin v1.2.0
|
||
|
||
# 查看标签
|
||
git tag -l
|
||
```
|
||
|
||
## .gitignore 配置
|
||
|
||
```gitignore
|
||
# Python
|
||
__pycache__/
|
||
*.py[cod]
|
||
*.egg-info/
|
||
dist/
|
||
build/
|
||
venv/
|
||
|
||
# 环境配置
|
||
.env
|
||
|
||
# IDE
|
||
.idea/
|
||
.vscode/
|
||
*.swp
|
||
|
||
# 上传文件
|
||
uploads/
|
||
|
||
# 日志
|
||
logs/
|
||
|
||
# 数据库
|
||
*.sqlite3
|
||
```
|
||
|
||
:::tip .env 安全
|
||
`.env` 文件包含敏感信息（数据库密码、JWT 密钥等），必须在 `.gitignore` 中排除。各环境的 `.env` 独立管理，不提交到仓库。
|
||
:::
|
||
|
||
## 常用 Git 命令
|
||
|
||
```bash
|
||
# 查看提交历史
|
||
git log --oneline -20
|
||
|
||
# 查看某次提交的变更
|
||
git show <commit-hash>
|
||
|
||
# 撤销工作区修改
|
||
git checkout -- <file>
|
||
|
||
# 撤销暂存
|
||
git reset HEAD <file>
|
||
|
||
# 暂存当前工作
|
||
git stash
|
||
git stash pop
|
||
|
||
# 查看分支图
|
||
git log --graph --oneline --all
|
||
```
|
||
|
||
## 总结
|
||
|
||
Git 提交规范采用 Conventional Commits 格式：`type(scope): subject`。常用类型包括 feat/fix/docs/refactor/test/chore。分支策略：main（生产）、master（开发）、feature/fix/hotfix（临时分支）。版本使用语义化标签（v1.2.0）。`.env` 等敏感文件必须排除在仓库之外。
|