xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases 7 Wiki Activity
Files
v2.1.0-test.6
xiaoxia-saas/docs/GIT-WORKFLOW.md
T
Xiaoxia AI 71a57001e0 ci: add CI/CD pipeline configuration 
- 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.
2026-06-18 15:51:27 +08:00

7.7 KiB
Raw Permalink Blame History

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

二、日常开发流程

开发新功能

# 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

# 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）

# 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（基础设施）

完整示例

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 描述模板

## 变更内容

简要描述本次 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（仅紧急情况）

git commit --no-verify -m "emergency fix"

六、版本发布流程

准备发布

# 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

发布到生产

# 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: 如何撤销最后一次提交？

# 保留改动
git reset --soft HEAD^

# 丢弃改动
git reset --hard HEAD^

Q2: 如何修改最后一次提交信息？

git commit --amend -m "new message"

Q3: 如何合并多个提交？

# 合并最近 3 个提交
git rebase -i HEAD~3
# 在编辑器中将 pick 改为 squash

Q4: 如何解决冲突？

# 1. 拉取最新代码
git pull origin develop

# 2. 手动解决冲突
# 编辑冲突文件

# 3. 标记为已解决
git add <resolved-files>

# 4. 继续
git rebase --continue
# 或
git merge --continue

Q5: 如何同步 fork 的仓库？

# 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
维护人: 小虾 🦐

Reference in New Issue View Git Blame Copy Permalink