git-workflow

Git Workflow (Git 工作流)

Goal: 规范化 Git 操作，确保提交历史清晰、可追溯、自动化友好。

---

1. Conventional Commits

提交格式

<type>(<scope>): <subject>

[optional body]

[optional footer]

Type 类型

Type	说明	示例
feat	新功能	feat(chat): add streaming response
fix	修复 Bug	fix(wallet): handle disconnect state
docs	文档更新	docs(readme): update installation
style	代码格式	style: format with prettier
refactor	重构	refactor(api): extract service layer
perf	性能优化	perf(query): add database index
test	测试	test(auth): add unit tests
chore	构建/工具	chore(deps): update dependencies
ci	CI 配置	ci: add github actions

Scope 范围 (项目特定)

AI 项目常用:
- chat, prompt, model, stream, agent

Web3 项目常用:
- wallet, tx, contract, chain, sign

通用:
- api, auth, db, ui, config

Subject 规则

• 使用祈使句 ("add" 而非 "added")
• 首字母小写
• 不加句号
• 限制 50 字符

示例

# 简单
feat(chat): add message history

# 带 body
fix(wallet): handle network switch during transaction

The wallet would crash when user switches network while
a transaction is pending. Now we cancel the pending tx
and show an error message.

# 带 breaking change
feat(api)!: change response format to JSON:API

BREAKING CHANGE: API responses now follow JSON:API spec.
Old format is no longer supported.

---

2. Branch Naming

格式

<type>/<ticket>-<description>

示例

feat/PROJ-123-add-wallet-connect
fix/PROJ-456-streaming-timeout
refactor/no-ticket-cleanup-hooks
hotfix/critical-security-patch

分支策略 (Trunk-Based for OPC)

main (production)
  ↑
  └── feat/xxx (short-lived feature branches)
  └── fix/xxx
  └── hotfix/xxx (直接合并 main)

OPC 简化原则:

• 不需要 develop 分支
• Feature 分支尽快合并 (1-3 天)
• Hotfix 直接从 main 创建并合并

---

3. Pull Request Template

模板 (.github/pull_request_template.md)

## Summary
<!-- 一句话描述这个 PR 做了什么 -->

## Changes
<!-- 列出主要变更 -->
- 
- 
- 

## Type
<!-- 选择一个 -->
- [ ] feat: 新功能
- [ ] fix: Bug 修复
- [ ] refactor: 重构
- [ ] docs: 文档
- [ ] test: 测试
- [ ] chore: 其他

## Testing
<!-- 如何验证这些变更 -->
- [ ] 本地测试通过
- [ ] 单元测试通过
- [ ] E2E 测试通过 (如适用)

## Screenshots
<!-- 如有 UI 变更，附截图 -->

## Checklist
- [ ] 代码已自审
- [ ] 无 console.log
- [ ] 类型定义完整
- [ ] 文档已更新 (如需要)

PR 标题规范

遵循 Conventional Commits 格式：

feat(chat): add streaming response support
fix(wallet): handle disconnect state
refactor(api): extract service layer

---

4. Commit Message Templates

Git 配置

# 设置提交模板
git config --global commit.template ~/.gitmessage

# ~/.gitmessage
# <type>(<scope>): <subject>
#
# <body>
#
# <footer>
#
# Types: feat, fix, docs, style, refactor, perf, test, chore, ci
# Scope: chat, wallet, api, auth, ui, config, etc.
# Subject: imperative, lowercase, no period, max 50 chars
# Body: explain what and why (not how), wrap at 72 chars
# Footer: BREAKING CHANGE, Closes #issue

快速提交脚本

# scripts/commit.sh
#!/bin/bash

types=("feat" "fix" "docs" "style" "refactor" "perf" "test" "chore" "ci")

echo "Select type:"
select type in "${types[@]}"; do
  break
done

read -p "Scope (optional): " scope
read -p "Subject: " subject

if [ -n "$scope" ]; then
  git commit -m "$type($scope): $subject"
else
  git commit -m "$type: $subject"
fi

---

5. Changelog Generation

自动生成 (使用 conventional-changelog)

# 安装
pnpm add -D conventional-changelog-cli

# 生成
npx conventional-changelog -p angular -i CHANGELOG.md -s

手动模板

# Changelog

## [1.2.0] - 2024-01-15

### Added
- feat(chat): streaming response support
- feat(wallet): multi-chain support

### Fixed
- fix(api): rate limiting edge case
- fix(ui): mobile responsive issues

### Changed
- refactor(auth): simplify token refresh logic

### Security
- security: upgrade vulnerable dependencies

---

6. Release Workflow

版本号规范 (SemVer)

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  (patch: bug fixes)
1.0.0 → 1.1.0  (minor: new features, backward compatible)
1.0.0 → 2.0.0  (major: breaking changes)

发布流程

# 1. 确保 main 分支最新
git checkout main && git pull

# 2. 更新版本号
npm version minor  # 或 major/patch

# 3. 生成 changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

# 4. 提交
git add CHANGELOG.md
git commit --amend --no-edit

# 5. 推送 (包含 tag)
git push && git push --tags

# 6. GitHub 自动发布 (通过 CI)

GitHub Release 模板

## What's New

### Features
- ✨ Streaming response support (#123)
- ✨ Multi-chain wallet connection (#124)

### Bug Fixes
- ? Fixed rate limiting edge case (#125)

### Breaking Changes
- ⚠️ API response format changed to JSON:API

## Upgrade Guide

If you're upgrading from v1.x:
1. Update API client to handle new response format
2. ...

## Full Changelog
https://github.com/user/repo/compare/v1.1.0...v1.2.0

---

7. Git Hooks

Husky 配置

# 安装
pnpm add -D husky
pnpm exec husky init

Pre-commit Hook

# .husky/pre-commit
pnpm lint-staged

Commit-msg Hook (验证格式)

# .husky/commit-msg
npx --no -- commitlint --edit $1

commitlint 配置

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', [
      'chat', 'wallet', 'api', 'auth', 'ui', 'config',
      'prompt', 'model', 'tx', 'contract'
    ]],
  },
}

lint-staged 配置

// lint-staged.config.js
module.exports = {
  '*.{ts,tsx}': ['eslint --fix', 'prettier --write'],
  '*.{json,md}': ['prettier --write'],
}

---

Quick Reference

常用命令

# 交互式暂存
git add -p

# 修改最后一次提交
git commit --amend

# 压缩多个提交
git rebase -i HEAD~3

# 查看美化日志
git log --oneline --graph

# 临时保存
git stash
git stash pop

Commit Message 速查

feat:     新功能
fix:      修复
docs:     文档
style:    格式
refactor: 重构
perf:     性能
test:     测试
chore:    杂项
ci:       CI/CD

分支命令

# 创建并切换
git checkout -b feat/new-feature

# 删除本地分支
git branch -d feat/merged-branch

# 删除远程分支
git push origin --delete feat/old-branch