Git Workflow

Git Workflow - Git 工作流专家

与 bensz-collect-bugs 的协作约定

• 因本 skill 设计缺陷导致的 bug，先用 bensz-collect-bugs 规范记录到 ~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。
• 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地 gh 上传新增 bug 到 huangwb8/bensz-bugs；不要 pull / clone 整个仓库。

核心理念

良好的 Git 实践 是团队协作的基础：

┌─────────────────────────────────────────────────────────┐
│  规范提交 → 清晰历史 → 易于回溯 → 高效协作              │
└─────────────────────────────────────────────────────────┘

核心原则：

• ✅ 提交历史即文档
• ✅ 原子提交，单一职责
• ✅ 清晰的可追溯性
• ✅ 易于 Code Review

---

何时使用本技能

在以下场景时激活：

• 需要 Git 提交（commit）
• 创建 Pull Request / Merge Request
• 代码分支管理
• 版本发布
• 提到"git"、"提交"、"分支"、"PR"

---

Conventional Commits 规范

提交格式

(): 

Type 类型

| Type | 说明 | 示例 | |------|------|------| | feat | 新功能 | feat(auth): add OAuth2 login | | fix | Bug 修复 | fix(api): resolve timeout issue | | docs | 文档变更 | docs(readme): update installation | | style | 代码格式 | style(lint): fix indentation | | refactor | 重构 | refactor(utils): extract validator | | perf | 性能优化 | perf(db): add query index | | test | 测试相关 | test(user): add login tests | | chore | 构建/工具 | chore(deps): upgrade to v2.0 | | revert | 回滚提交 | revert: feat(auth) |

提交示例

# 简单提交
feat(auth): add JWT token validation

# 完整提交
feat(payment): integrate Stripe payment gateway

Implement credit card payment processing using Stripe API.
Add webhook handling for payment status updates.

- Add Stripe client initialization
- Implement payment intent creation
- Add webhook endpoint for status updates
- Handle payment success/failure scenarios

Closes #123
Related #456

---

提交最佳实践

1. 原子提交原则

# ❌ 不好的做法：一次提交多个变更
git commit -m "feat: add user feature and fix bugs and update docs"

# ✅ 好的做法：每个提交一个职责
git commit -m "feat(user): add registration"
git commit -m "fix(auth): resolve session timeout"
git commit -m "docs(readme): update examples"

2. 提交大小控制

| 类型 | 行数变化 | 建议 | |------|----------|------| | 小型 | 400 行 | ❌ 应拆分 |

3. 提交信息质量

# ❌ 不好的提交信息
git commit -m "update"
git commit -m "fix bug"
git commit -m "wip"

# ✅ 好的提交信息
git commit -m "fix(auth): resolve JWT validation error"
git commit -m "feat(api): add rate limiting middleware"
git commit -m "docs(guide): explain authentication flow"

---

分支管理策略

分支命名规范

| 类型 | 格式 | 示例 | |------|------|------| | 功能 | feature/* | feature/user-auth | | 修复 | bugfix/* | bugfix/login-timeout | | 热修复 | hotfix/* | hotfix/security-patch | | 发布 | release/* | release/v1.2.0 | | 实验 | experiment/* | experiment/new-ui |

分支工作流

main (生产)
  ↑
  ├── release/v1.2.0 (发布准备)
  │     ↑
  │     ├── feature/user-auth (功能开发)
  │     ├── feature/payment-api (功能开发)
  │     └── bugfix/login-issue (Bug 修复)
  │
  └── hotfix/security-patch (紧急修复)

分支最佳实践

# 1. 从 main 创建功能分支
git checkout main
git pull origin main
git checkout -b feature/user-auth

# 2. 开发并提交
git add .
git commit -m "feat(auth): add login endpoint"

# 3. 同步上游变更
git fetch origin main
git rebase origin/main

# 4. 推送到远程
git push origin feature/user-auth

# 5. 创建 Pull Request
# (通过 GitHub/GitLab 界面)

---

Pull Request 最佳实践

PR 标题格式

与 Conventional Commits 保持一致：

feat(auth): add OAuth2 login support

fix(api): resolve timeout issue

docs(readme): update installation guide

PR 描述模板

## 📝 变更类型
- [x] ✨ feat 新功能
- [ ] 🐛 fix Bug修复
- [ ] ♻️  refactor 重构
- [ ] 📚 docs 文档
- [ ] 💄 style 代码格式
- [ ] ⚡ perf 性能优化
- [ ] ✅ test 测试
- [ ] 🔧 chore 构建/工具

## 🎯 变更说明

这个 PR 实现了用户认证功能，包括：
- JWT token 生成和验证
- 登录/登出端点
- 中间件保护路由

## 🔄 变更内容

- `src/auth/login.py` - 登录逻辑
- `src/auth/middleware.py` - 认证中间件
- `tests/test_auth.py` - 测试用例

## 🧪 测试

- [x] 添加了单元测试
- [x] 添加了集成测试
- [x] 手动测试通过
- [ ] 性能测试通过

## ✅ 检查清单

- [x] 代码符合团队规范
- [x] 自我审查完成
- [x] 注释充分且准确
- [x] 文档已更新
- [x] 测试覆盖充分
- [x] 无合并冲突

## 📸 截图/演示

## 🔗 相关链接
- Closes #123
- Related #456
- Depends on #789

## ⚠️ 注意事项

需要特别注意 JWT secret 的配置，已在 .env.example 中说明。

PR 审查响应

## 审查反馈

### 需要修改
- [ ] 安全问题：SQL 注入风险 (user_service.py:45)
- [ ] 性能问题：N+1 查询 (api.py:78)

### 建议改进
- [ ] 命名：`d()` → `double_value()` (utils.py:12)
- [ ] 注释：补充复杂逻辑说明 (payment.py:34)

### LGTM with suggestions
- [ ] 可以合并，但建议后续优化

---

Git Hooks 自动化

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# 运行 linter
npm run lint
if [ $? -ne 0 ]; then
    echo "❌ Lint failed, please fix before committing"
    exit 1
fi

# 运行测试
npm test
if [ $? -ne 0 ]; then
    echo "❌ Tests failed, please fix before committing"
    exit 1
fi

echo "✅ Pre-commit checks passed"

Commit Message Hook

#!/bin/bash
# .git/hooks/commit-msg

# 验证提交信息格式
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|revert)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "❌ Invalid commit message format"
    echo "✅ Expected format: (): "
    exit 1
fi

echo "✅ Commit message format valid"

---

常见操作

修改最后一次提交

# 添加遗漏的文件
git add forgotten_file.py

# 修改提交信息
git commit --amend

# 修改提交内容但不改信息
git commit --amend --no-edit

撤销提交

# 撤销最后一次提交（保留变更）
git reset --soft HEAD~1

# 撤销最后一次提交（丢弃变更）
git reset --hard HEAD~1

# 撤销多次提交
git reset --soft HEAD~3

交互式变基

# 变基最近 3 个提交
git rebase -i HEAD~3

# 命令：
# pick  - 保留提交
# reword - 修改提交信息
# edit - 编辑提交
# squash - 合并到前一个提交
# drop - 删除提交

解决合并冲突

# 1. 开始变基
git rebase origin/main

# 2. 遇到冲突时
git status  # 查看冲突文件

# 3. 手动解决冲突
# 编辑冲突文件，删除 >>>>>> 标记

# 4. 标记冲突已解决
git add 

# 5. 继续变基
git rebase --continue

# 6. 如果需要放弃
git rebase --abort

---

验证清单

提交或 PR 前，检查：

• [ ] 提交信息符合 Conventional Commits 规范
• [ ] 每个提交职责单一
• [ ] 提交大小合理（< 400 行）
• [ ] 分支命名符合规范
• [ ] 无敏感信息泄露
• [ ] 关联 Issue/PR
• [ ] 代码已通过测试
• [ ] 文档已更新

---

相关参考

• [Git 工作流规范](../references/git-workflow.md)
• Conventional Commits

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: huangwb8
• Source: huangwb8/skills
• License: MIT

Install and usage instructions live in the source repository linked above.