docs: salvage zh-CN core skill translations

2026-05-18 06:43:05 +08:00 · 2026-05-11 14:09:27 -04:00
parent 6556f20af7
commit 3242ed461f
15 changed files with 2945 additions and 0 deletions
--- a/docs/zh-CN/skills/git-workflow/SKILL.md
+++ b/docs/zh-CN/skills/git-workflow/SKILL.md
@@ -0,0 +1,720 @@
+---
+name: git-workflow
+description: Git工作流模式，包括分支策略、提交约定、合并与变基、冲突解决以及适用于各种规模团队的协作开发最佳实践。
+origin: ECC
+---
+
+# Git 工作流模式
+
+Git 版本控制、分支策略与协作开发的最佳实践。
+
+## 何时启用
+
+* 为新项目设置 Git 工作流
+* 决定分支策略（GitFlow、主干开发、GitHub Flow）
+* 编写提交信息和 PR 描述
+* 解决合并冲突
+* 管理发布和版本标签
+* 让新团队成员熟悉 Git 实践
+
+## 分支策略
+
+### GitHub Flow（简单，推荐大多数场景使用）
+
+最适合持续部署以及中小型团队。
+
+```
+main (protected, always deployable)
+  │
+  ├── feature/user-auth      → PR → merge to main
+  ├── feature/payment-flow   → PR → merge to main
+  └── fix/login-bug          → PR → merge to main
+```
+
+**规则：**
+
+* `main` 始终可部署
+* 从 `main` 创建功能分支
+* 准备就绪后发起 Pull Request
+* 审核通过且 CI 通过后，合并到 `main`
+* 合并后立即部署
+
+### 主干开发（高速度团队）
+
+最适合具备强大 CI/CD 和功能开关的团队。
+
+```
+main (主干)
+  │
+  ├── 短期功能分支（最长1-2天）
+  ├── 短期功能分支
+  └── 短期功能分支
+```
+
+**规则：**
+
+* 所有人直接提交到 `main` 或使用极短生命周期的分支
+* 功能开关隐藏未完成的工作
+* 合并前必须通过 CI
+* 每天多次部署
+
+### GitFlow（复杂，基于发布周期）
+
+适合计划性发布和企业级项目。
+
+```
+main (生产发布版本)
+  │
+  └── develop (集成分支)
+        │
+        ├── feature/user-auth
+        ├── feature/payment
+        │
+        ├── release/1.0.0    → 合并到 main 和 develop
+        │
+        └── hotfix/critical  → 合并到 main 和 develop
+```
+
+**规则：**
+
+* `main` 仅包含生产就绪代码
+* `develop` 是集成分支
+* 功能分支从 `develop` 创建，合并回 `develop`
+* 发布分支从 `develop` 创建，合并到 `main` 和 `develop`
+* 热修复分支从 `main` 创建，合并到 `main` 和 `develop`
+
+### 何时使用哪种策略
+
+| 策略 | 团队规模 | 发布频率 | 最佳适用场景 |
+|----------|-----------|-----------------|----------|
+| GitHub Flow | 任意 | 持续 | SaaS、Web 应用、初创公司 |
+| 主干开发 | 5 人以上有经验 | 每天多次 | 高速度团队、功能开关 |
+| GitFlow | 10 人以上 | 计划性 | 企业、受监管行业 |
+
+## 提交信息
+
+### 常规提交格式
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### 类型
+
+| 类型 | 用途 | 示例 |
+|------|---------|---------|
+| `feat` | 新功能 | `feat(auth): add OAuth2 login` |
+| `fix` | 错误修复 | `fix(api): handle null response in user endpoint` |
+| `docs` | 文档 | `docs(readme): update installation instructions` |
+| `style` | 格式调整，无代码变更 | `style: fix indentation in login component` |
+| `refactor` | 代码重构 | `refactor(db): extract connection pool to module` |
+| `test` | 添加/更新测试 | `test(auth): add unit tests for token validation` |
+| `chore` | 维护任务 | `chore(deps): update dependencies` |
+| `perf` | 性能改进 | `perf(query): add index to users table` |
+| `ci` | CI/CD 变更 | `ci: add PostgreSQL service to test workflow` |
+| `revert` | 回滚之前的提交 | `revert: revert "feat(auth): add OAuth2 login"` |
+
+### 好与坏的示例
+
+```
+# 不好：模糊，无上下文
+git commit -m "修复了一些东西"
+git commit -m "更新"
+git commit -m "进行中"
+
+# 好：清晰，具体，解释原因
+git commit -m "fix(api): 在 503 服务不可用时重试请求
+
+外部 API 在高峰时段偶尔会返回 503 错误。
+添加了指数退避重试逻辑，最多尝试 3 次。
+
+关闭 #123"
+```
+
+### 提交信息模板
+
+在仓库根目录创建 `.gitmessage`：
+
+```
+# <type>(<scope>): <subject>
+# # 类型：feat, fix, docs, style, refactor, test, chore, perf, ci, revert
+# 范围：api, ui, db, auth 等
+# 主题：祈使语气，无句号，最多50个字符
+#
+# [可选正文] - 解释原因，而非内容
+# [可选脚注] - 破坏性变更，关闭 #issue
+```
+
+启用方式：`git config commit.template .gitmessage`
+
+## 合并 vs 变基
+
+### 合并（保留历史）
+
+```bash
+# Creates a merge commit
+git checkout main
+git merge feature/user-auth
+
+# Result:
+# *   merge commit
+# |\
+# | * feature commits
+# |/
+# * main commits
+```
+
+**适用场景：**
+
+* 将功能分支合并到 `main`
+* 希望保留完整历史
+* 多人共同开发该分支
+* 分支已推送，其他人可能基于它开展工作
+
+### 变基（线性历史）
+
+```bash
+# Rewrites feature commits onto target branch
+git checkout feature/user-auth
+git rebase main
+
+# Result:
+# * feature commits (rewritten)
+# * main commits
+```
+
+**适用场景：**
+
+* 用最新的 `main` 更新本地功能分支
+* 希望获得线性、干净的历史
+* 分支仅存在于本地（未推送）
+* 只有你一个人在该分支上工作
+
+### 变基工作流
+
+```bash
+# Update feature branch with latest main (before PR)
+git checkout feature/user-auth
+git fetch origin
+git rebase origin/main
+
+# Fix any conflicts
+# Tests should still pass
+
+# Force push (only if you're the only contributor)
+git push --force-with-lease origin feature/user-auth
+```
+
+### 何时不应变基
+
+```
+# 切勿变基以下分支：
+- 已推送至共享仓库的分支
+- 他人已基于其工作的分支
+- 受保护分支（main、develop）
+- 已合并的分支
+
+# 原因：变基会重写历史，破坏他人的工作
+```
+
+## Pull Request 工作流
+
+### PR 标题格式
+
+```
+<type>(<scope>): <description>
+
+示例：
+feat(auth): add SSO support for enterprise users
+fix(api): resolve race condition in order processing
+docs(api): add OpenAPI specification for v2 endpoints
+```
+
+### PR 描述模板
+
+```markdown
+## 内容
+
+简要描述此 PR 的内容。
+
+## 动机
+
+解释动机和背景。
+
+## 实现方式
+
+值得强调的关键实现细节。
+
+## 测试
+
+- [ ] 新增/更新单元测试
+- [ ] 新增/更新集成测试
+- [ ] 执行手动测试
+
+## 截图（如适用）
+
+UI 变更的前后对比截图。
+
+## 检查清单
+
+- [ ] 代码遵循项目风格指南
+- [ ] 完成自我审查
+- [ ] 为复杂逻辑添加注释
+- [ ] 更新文档
+- [ ] 未引入新警告
+- [ ] 测试在本地通过
+- [ ] 关联问题已链接
+
+关闭 #123
+```
+
+### 代码审查清单
+
+**审查者：**
+
+* \[ ] 代码是否解决了所述问题？
+* \[ ] 是否处理了所有边界情况？
+* \[ ] 代码是否可读且易于维护？
+* \[ ] 是否有足够的测试？
+* \[ ] 是否存在安全问题？
+* \[ ] 提交历史是否干净（必要时已压缩）？
+
+**作者：**
+
+* \[ ] 在请求审查前已完成自我审查
+* \[ ] CI 通过（测试、lint、类型检查）
+* \[ ] PR 大小合理（理想情况下 <500 行）
+* \[ ] 与单个功能/修复相关
+* \[ ] 描述清晰解释了变更内容
+
+## 冲突解决
+
+### 识别冲突
+
+```bash
+# Check for conflicts before merge
+git checkout main
+git merge feature/user-auth --no-commit --no-ff
+
+# If conflicts, Git will show:
+# CONFLICT (content): Merge conflict in src/auth/login.ts
+# Automatic merge failed; fix conflicts and then commit the result.
+```
+
+### 解决冲突
+
+```bash
+# See conflicted files
+git status
+
+# View conflict markers in file
+# <<<<<<< HEAD
+# content from main
+# =======
+# content from feature branch
+# >>>>>>> feature/user-auth
+
+# Option 1: Manual resolution
+# Edit file, remove markers, keep correct content
+
+# Option 2: Use merge tool
+git mergetool
+
+# Option 3: Accept one side
+git checkout --ours src/auth/login.ts    # Keep main version
+git checkout --theirs src/auth/login.ts  # Keep feature version
+
+# After resolving, stage and commit
+git add src/auth/login.ts
+git commit
+```
+
+### 冲突预防策略
+
+```bash
+# 1. Keep feature branches small and short-lived
+# 2. Rebase frequently onto main
+git checkout feature/user-auth
+git fetch origin
+git rebase origin/main
+
+# 3. Communicate with team about touching shared files
+# 4. Use feature flags instead of long-lived branches
+# 5. Review and merge PRs promptly
+```
+
+## 分支管理
+
+### 命名规范
+
+```
+# 功能分支
+feature/user-authentication
+feature/JIRA-123-payment-integration
+
+# 错误修复
+fix/login-redirect-loop
+fix/456-null-pointer-exception
+
+# 热修复（生产问题）
+hotfix/critical-security-patch
+hotfix/database-connection-leak
+
+# 发布版本
+release/1.2.0
+release/2024-01-hotfix
+
+# 实验/概念验证
+experiment/new-caching-strategy
+poc/graphql-migration
+```
+
+### 分支清理
+
+```bash
+# Delete local branches that are merged
+git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d
+
+# Delete remote-tracking references for deleted remote branches
+git fetch -p
+
+# Delete local branch
+git branch -d feature/user-auth  # Safe delete (only if merged)
+git branch -D feature/user-auth  # Force delete
+
+# Delete remote branch
+git push origin --delete feature/user-auth
+```
+
+### 暂存工作流
+
+```bash
+# Save work in progress
+git stash push -m "WIP: user authentication"
+
+# List stashes
+git stash list
+
+# Apply most recent stash
+git stash pop
+
+# Apply specific stash
+git stash apply stash@{2}
+
+# Drop stash
+git stash drop stash@{0}
+```
+
+## 发布管理
+
+### 语义化版本
+
+```
+MAJOR.MINOR.PATCH
+
+MAJOR：破坏性变更
+MINOR：新功能，向后兼容
+PATCH：错误修复，向后兼容
+
+示例：
+1.0.0 → 1.0.1（补丁：错误修复）
+1.0.1 → 1.1.0（次要：新功能）
+1.1.0 → 2.0.0（主要：破坏性变更）
+```
+
+### 创建发布
+
+```bash
+# Create annotated tag
+git tag -a v1.2.0 -m "Release v1.2.0
+
+Features:
+- Add user authentication
+- Implement password reset
+
+Fixes:
+- Resolve login redirect issue
+
+Breaking Changes:
+- None"
+
+# Push tag to remote
+git push origin v1.2.0
+
+# List tags
+git tag -l
+
+# Delete tag
+git tag -d v1.2.0
+git push origin --delete v1.2.0
+```
+
+### 变更日志生成
+
+```bash
+# Generate changelog from commits
+git log v1.1.0..v1.2.0 --oneline --no-merges
+
+# Or use conventional-changelog
+npx conventional-changelog -i CHANGELOG.md -s
+```
+
+## Git 配置
+
+### 基本配置
+
+```bash
+# User identity
+git config --global user.name "Your Name"
+git config --global user.email "your@email.com"
+
+# Default branch name
+git config --global init.defaultBranch main
+
+# Pull behavior (rebase instead of merge)
+git config --global pull.rebase true
+
+# Push behavior (push current branch only)
+git config --global push.default current
+
+# Auto-correct typos
+git config --global help.autocorrect 1
+
+# Better diff algorithm
+git config --global diff.algorithm histogram
+
+# Color output
+git config --global color.ui auto
+```
+
+### 实用别名
+
+```bash
+# Add to ~/.gitconfig
+[alias]
+    co = checkout
+    br = branch
+    ci = commit
+    st = status
+    unstage = reset HEAD --
+    last = log -1 HEAD
+    visual = log --oneline --graph --all
+    amend = commit --amend --no-edit
+    wip = commit -m "WIP"
+    undo = reset --soft HEAD~1
+    contributors = shortlog -sn
+```
+
+### Gitignore 模式
+
+```gitignore
+# Dependencies
+node_modules/
+vendor/
+
+# Build outputs
+dist/
+build/
+*.o
+*.exe
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test coverage
+coverage/
+
+# Cache
+.cache/
+*.tsbuildinfo
+```
+
+## 常见工作流
+
+### 开始新功能
+
+```bash
+# 1. Update main branch
+git checkout main
+git pull origin main
+
+# 2. Create feature branch
+git checkout -b feature/user-auth
+
+# 3. Make changes and commit
+git add .
+git commit -m "feat(auth): implement OAuth2 login"
+
+# 4. Push to remote
+git push -u origin feature/user-auth
+
+# 5. Create Pull Request on GitHub/GitLab
+```
+
+### 用新变更更新 PR
+
+```bash
+# 1. Make additional changes
+git add .
+git commit -m "feat(auth): add error handling"
+
+# 2. Push updates
+git push origin feature/user-auth
+```
+
+### 同步 Fork 与上游
+
+```bash
+# 1. Add upstream remote (once)
+git remote add upstream https://github.com/original/repo.git
+
+# 2. Fetch upstream
+git fetch upstream
+
+# 3. Merge upstream/main into your main
+git checkout main
+git merge upstream/main
+
+# 4. Push to your fork
+git push origin main
+```
+
+### 撤销错误操作
+
+```bash
+# Undo last commit (keep changes)
+git reset --soft HEAD~1
+
+# Undo last commit (discard changes)
+git reset --hard HEAD~1
+
+# Undo last commit pushed to remote
+git revert HEAD
+git push origin main
+
+# Undo specific file changes
+git checkout HEAD -- path/to/file
+
+# Fix last commit message
+git commit --amend -m "New message"
+
+# Add forgotten file to last commit
+git add forgotten-file
+git commit --amend --no-edit
+```
+
+## Git 钩子
+
+### 预提交钩子
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Run linting
+npm run lint || exit 1
+
+# Run tests
+npm test || exit 1
+
+# Check for secrets
+if git diff --cached | grep -E '(password|api_key|secret)'; then
+    echo "Possible secret detected. Commit aborted."
+    exit 1
+fi
+```
+
+### 预推送钩子
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-push
+
+# Run full test suite
+npm run test:all || exit 1
+
+# Check for console.log statements
+if git diff origin/main | grep -E 'console\.log'; then
+    echo "Remove console.log statements before pushing."
+    exit 1
+fi
+```
+
+## 反模式
+
+```
+# 错误：直接提交到主分支
+git checkout main
+git commit -m "修复bug"
+
+# 正确：使用功能分支和拉取请求
+
+# 错误：提交机密信息
+git add .env  # 包含API密钥
+
+# 正确：添加到.gitignore，使用环境变量
+
+# 错误：巨大的拉取请求（超过1000行）
+# 正确：拆分为更小、更聚焦的拉取请求
+
+# 错误："更新"类提交信息
+git commit -m "更新"
+git commit -m "修复"
+
+# 正确：描述性信息
+git commit -m "fix(auth): 解决登录后的重定向循环问题"
+
+# 错误：重写公共历史
+git push --force origin main
+
+# 正确：对公共分支使用回退
+git revert HEAD
+
+# 错误：长期存在的功能分支（数周/数月）
+# 正确：保持分支短期（数天），频繁变基
+
+# 错误：提交生成的文件
+git add dist/
+git add node_modules/
+
+# 正确：添加到.gitignore
+```
+
+## 快速参考
+
+| 任务 | 命令 |
+|------|---------|
+| 创建分支 | `git checkout -b feature/name` |
+| 切换分支 | `git checkout branch-name` |
+| 删除分支 | `git branch -d branch-name` |
+| 合并分支 | `git merge branch-name` |
+| 变基分支 | `git rebase main` |
+| 查看历史 | `git log --oneline --graph` |
+| 查看变更 | `git diff` |
+| 暂存变更 | `git add .` 或 `git add -p` |
+| 提交 | `git commit -m "message"` |
+| 推送 | `git push origin branch-name` |
+| 拉取 | `git pull origin branch-name` |
+| 暂存 | `git stash push -m "message"` |
+| 撤销上次提交 | `git reset --soft HEAD~1` |
+| 回滚提交 | `git revert HEAD` |