Xiaoxia AI
71a57001e0
- Add Gitea Actions workflow - Stage 1: Code quality check (black, isort, mypy, flake8, bandit) - Stage 2: Automated testing (unit + integration tests) - Stage 3: Build backend Docker images - Stage 4: Build frontend static assets - Stage 5: Deploy to staging (develop branch) - Stage 6: Deploy to production (main branch) Also add Git workflow documentation.
390 lines
7.7 KiB
Markdown
390 lines
7.7 KiB
Markdown
# Git 工作流操作手册
|
||
|
||
**版本**: v1.0
|
||
**创建时间**: 2026-06-18
|
||
**适用项目**: 小虾 SaaS
|
||
|
||
---
|
||
|
||
## 一、分支结构
|
||
|
||
### 主要分支
|
||
|
||
| 分支 | 用途 | 保护级别 | 合并要求 |
|
||
|------|------|----------|----------|
|
||
| **main** | 生产稳定版本 | 🔒 最高 | PR + 2 人 Review + CI 通过 |
|
||
| **develop** | 开发主线 | 🔒 高 | PR + 1 人 Review + CI 通过 |
|
||
|
||
### 临时分支
|
||
|
||
| 分支类型 | 命名 | 从哪里创建 | 合并到 | 示例 |
|
||
|---------|------|-----------|--------|------|
|
||
| **feature/** | feature/功能名 | develop | develop | feature/asset-upload |
|
||
| **bugfix/** | bugfix/bug描述 | develop | develop | bugfix/login-timeout |
|
||
| **hotfix/** | hotfix/紧急修复 | main | main + develop | hotfix/payment-crash |
|
||
| **release/** | release/版本号 | develop | main + develop | release/v1.2.0 |
|
||
|
||
---
|
||
|
||
## 二、日常开发流程
|
||
|
||
### 开发新功能
|
||
|
||
```bash
|
||
# 1. 确保 develop 是最新的
|
||
git checkout develop
|
||
git pull origin develop
|
||
|
||
# 2. 创建功能分支
|
||
git checkout -b feature/asset-upload
|
||
|
||
# 3. 开发 + 提交（多次）
|
||
git add .
|
||
git commit -m "feat(asset): implement OSS upload"
|
||
|
||
# 4. 推送到远程
|
||
git push -u origin feature/asset-upload
|
||
|
||
# 5. 在 Gitea 创建 Pull Request
|
||
# 访问: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/compare/develop...feature/asset-upload
|
||
|
||
# 6. 等待 CI 检查通过 + Review 通过
|
||
|
||
# 7. 合并到 develop（在网页上操作）
|
||
|
||
# 8. 删除本地分支
|
||
git checkout develop
|
||
git pull origin develop
|
||
git branch -d feature/asset-upload
|
||
```
|
||
|
||
### 修复 Bug
|
||
|
||
```bash
|
||
# 1. 从 develop 创建 bugfix 分支
|
||
git checkout develop
|
||
git pull origin develop
|
||
git checkout -b bugfix/login-timeout
|
||
|
||
# 2. 修复 + 提交
|
||
git add .
|
||
git commit -m "fix(auth): resolve login timeout issue"
|
||
|
||
# 3. 推送并创建 PR（同上）
|
||
```
|
||
|
||
### 紧急修复（Hotfix）
|
||
|
||
```bash
|
||
# 1. 从 main 创建 hotfix 分支
|
||
git checkout main
|
||
git pull origin main
|
||
git checkout -b hotfix/payment-crash
|
||
|
||
# 2. 快速修复
|
||
git add .
|
||
git commit -m "fix(payment): resolve null pointer crash"
|
||
|
||
# 3. 合并到 main
|
||
git checkout main
|
||
git merge --no-ff hotfix/payment-crash
|
||
git tag -a v1.1.1 -m "Hotfix: payment crash"
|
||
git push origin main --tags
|
||
|
||
# 4. 合并回 develop
|
||
git checkout develop
|
||
git merge --no-ff hotfix/payment-crash
|
||
git push origin develop
|
||
|
||
# 5. 删除 hotfix 分支
|
||
git branch -d hotfix/payment-crash
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Commit 规范
|
||
|
||
### 格式
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### Type 类型
|
||
|
||
| Type | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **feat** | 新功能 | feat(asset): add video upload |
|
||
| **fix** | Bug 修复 | fix(auth): resolve token issue |
|
||
| **docs** | 文档更新 | docs(api): update auth guide |
|
||
| **style** | 代码格式 | style(asset): format with black |
|
||
| **refactor** | 重构 | refactor(auth): extract JWT service |
|
||
| **perf** | 性能优化 | perf(query): add database index |
|
||
| **test** | 测试 | test(asset): add upload tests |
|
||
| **chore** | 构建/工具 | chore(deps): upgrade fastapi |
|
||
| **ci** | CI/CD | ci(github): add security scan |
|
||
| **revert** | 回滚 | revert: revert commit abc123 |
|
||
|
||
### Scope 范围
|
||
|
||
- asset（素材管理）
|
||
- auth（认证）
|
||
- workspace（工作空间）
|
||
- subscription（订阅）
|
||
- generation（视频生成）
|
||
- api（API 层）
|
||
- ui（前端）
|
||
- db（数据库）
|
||
- infra（基础设施）
|
||
|
||
### 完整示例
|
||
|
||
```bash
|
||
feat(asset): implement video classification
|
||
|
||
- Add AI model adapter for classification
|
||
- Add classification job queue
|
||
- Add classification result storage
|
||
- Update asset entity with classification fields
|
||
|
||
This implements the core classification feature defined in Phase 7.
|
||
|
||
Closes #234
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Pull Request 规范
|
||
|
||
### PR 标题
|
||
|
||
- 简洁明了，< 70 字符
|
||
- 格式同 Commit 格式：`<type>(<scope>): <subject>`
|
||
|
||
### PR 描述模板
|
||
|
||
```markdown
|
||
## 变更内容
|
||
|
||
简要描述本次 PR 的主要变更。
|
||
|
||
## 变更类型
|
||
|
||
- [ ] 新功能
|
||
- [ ] Bug 修复
|
||
- [ ] 文档更新
|
||
- [ ] 重构
|
||
- [ ] 性能优化
|
||
|
||
## 测试情况
|
||
|
||
- [ ] 单元测试通过
|
||
- [ ] 集成测试通过
|
||
- [ ] 手动测试完成
|
||
|
||
## 相关 Issue
|
||
|
||
Closes #123
|
||
|
||
## 截图（如有必要）
|
||
|
||
## 额外说明
|
||
```
|
||
|
||
### Review 检查清单
|
||
|
||
Reviewer 需要检查：
|
||
- [ ] 代码符合项目规范
|
||
- [ ] 遵循 Clean Architecture
|
||
- [ ] 类型注解完整
|
||
- [ ] 有足够的测试覆盖
|
||
- [ ] 文档已更新
|
||
- [ ] 无安全问题
|
||
- [ ] CI 检查全部通过
|
||
|
||
---
|
||
|
||
## 五、Git Hooks
|
||
|
||
### Pre-commit（提交前检查）
|
||
|
||
自动检查：
|
||
- 禁止直接提交到 main/develop
|
||
- Python 代码格式（black）
|
||
- Python 代码规范（flake8）
|
||
- TypeScript/JavaScript 规范（eslint）
|
||
|
||
### Commit-msg（提交信息检查）
|
||
|
||
自动检查：
|
||
- Commit 格式是否符合规范
|
||
- 必须包含 type 和 subject
|
||
|
||
### 绕过 Hooks（仅紧急情况）
|
||
|
||
```bash
|
||
git commit --no-verify -m "emergency fix"
|
||
```
|
||
|
||
---
|
||
|
||
## 六、版本发布流程
|
||
|
||
### 准备发布
|
||
|
||
```bash
|
||
# 1. 从 develop 创建 release 分支
|
||
git checkout develop
|
||
git pull origin develop
|
||
git checkout -b release/v1.2.0
|
||
|
||
# 2. 更新版本号
|
||
# 编辑 package.json, __version__.py 等
|
||
|
||
# 3. 生成 CHANGELOG
|
||
# 使用工具或手动整理
|
||
|
||
# 4. 提交版本更新
|
||
git commit -am "chore(release): prepare v1.2.0"
|
||
|
||
# 5. 推送并创建 PR 到 main
|
||
git push -u origin release/v1.2.0
|
||
```
|
||
|
||
### 发布到生产
|
||
|
||
```bash
|
||
# 1. 合并 release 到 main
|
||
git checkout main
|
||
git merge --no-ff release/v1.2.0
|
||
|
||
# 2. 打 tag
|
||
git tag -a v1.2.0 -m "Release version 1.2.0"
|
||
|
||
# 3. 推送
|
||
git push origin main --tags
|
||
|
||
# 4. 合并回 develop
|
||
git checkout develop
|
||
git merge --no-ff release/v1.2.0
|
||
git push origin develop
|
||
|
||
# 5. 删除 release 分支
|
||
git branch -d release/v1.2.0
|
||
git push origin --delete release/v1.2.0
|
||
```
|
||
|
||
---
|
||
|
||
## 七、常见问题
|
||
|
||
### Q1: 如何撤销最后一次提交？
|
||
|
||
```bash
|
||
# 保留改动
|
||
git reset --soft HEAD^
|
||
|
||
# 丢弃改动
|
||
git reset --hard HEAD^
|
||
```
|
||
|
||
### Q2: 如何修改最后一次提交信息？
|
||
|
||
```bash
|
||
git commit --amend -m "new message"
|
||
```
|
||
|
||
### Q3: 如何合并多个提交？
|
||
|
||
```bash
|
||
# 合并最近 3 个提交
|
||
git rebase -i HEAD~3
|
||
# 在编辑器中将 pick 改为 squash
|
||
```
|
||
|
||
### Q4: 如何解决冲突？
|
||
|
||
```bash
|
||
# 1. 拉取最新代码
|
||
git pull origin develop
|
||
|
||
# 2. 手动解决冲突
|
||
# 编辑冲突文件
|
||
|
||
# 3. 标记为已解决
|
||
git add <resolved-files>
|
||
|
||
# 4. 继续
|
||
git rebase --continue
|
||
# 或
|
||
git merge --continue
|
||
```
|
||
|
||
### Q5: 如何同步 fork 的仓库？
|
||
|
||
```bash
|
||
# 1. 添加上游仓库
|
||
git remote add upstream <upstream-url>
|
||
|
||
# 2. 拉取上游更新
|
||
git fetch upstream
|
||
|
||
# 3. 合并到本地
|
||
git merge upstream/main
|
||
```
|
||
|
||
---
|
||
|
||
## 八、最佳实践
|
||
|
||
### ✅ 应该做的
|
||
|
||
1. **经常提交** - 小步快跑，每个逻辑单元一个提交
|
||
2. **有意义的提交信息** - 清晰描述"做了什么"和"为什么"
|
||
3. **提交前测试** - 确保代码可运行
|
||
4. **及时 pull** - 保持本地代码最新
|
||
5. **Code Review** - 所有代码必须经过 Review
|
||
6. **保持分支干净** - 及时删除已合并的分支
|
||
|
||
### ❌ 不应该做的
|
||
|
||
1. **直接提交到 main/develop** - 必须通过 PR
|
||
2. **强制推送** - 除非你知道自己在做什么
|
||
3. **提交敏感信息** - 密码、密钥、token 等
|
||
4. **巨大的提交** - 一次提交改动太多文件
|
||
5. **无意义的提交信息** - "fix", "update", "change" 等
|
||
6. **跳过 CI 检查** - 必须等 CI 通过
|
||
|
||
---
|
||
|
||
## 九、仓库配置
|
||
|
||
### Gitea 分支保护设置
|
||
|
||
**访问**: https://api.xiaoxiajianji.com/git/xiaoxia/xiaoxia-saas/settings/branches
|
||
|
||
**main 分支**:
|
||
- ✅ 启用分支保护
|
||
- ✅ 禁止强制推送
|
||
- ✅ 禁止删除
|
||
- ✅ 需要 PR
|
||
- ✅ 需要 2 个 Reviews
|
||
- ✅ 需要 CI 通过
|
||
|
||
**develop 分支**:
|
||
- ✅ 启用分支保护
|
||
- ✅ 禁止强制推送
|
||
- ✅ 需要 PR
|
||
- ✅ 需要 1 个 Review
|
||
- ✅ 需要 CI 通过
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2026-06-18
|
||
**维护人**: 小虾 🦐
|