Back to Details

verification-before-merge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Verification Before Merge

合并前验证

Overview

概述

Final verification before merging. All gates must pass.
Core principle: Never merge without complete verification.
This is a HARD GATE. Do not merge with any failure.
合并前的最终验证，所有检查项必须全部通过。
核心原则： 未完成完整验证绝不要合并。
这是硬性检查关卡，任何失败都不允许合并。

The Gates

检查项

All must be GREEN to merge:
┌──────────────────────────────────────────────────────┐
│                  MERGE GATES                         │
├──────────────────────────────────────────────────────┤
│  [ ] CI Pipeline Green                               │
│  [ ] Local Integration Tests Pass (if services)     │
│  [ ] All Tests Pass                                  │
│  [ ] Code Review Approved                            │
│  [ ] Acceptance Criteria Verified                    │
│  [ ] No Unresolved Conversations                     │
│  [ ] Branch Up to Date                               │
│  [ ] No Merge Conflicts                              │
├──────────────────────────────────────────────────────┤
│  ALL GREEN → MERGE ALLOWED                           │
│  ANY RED → MERGE BLOCKED                             │
└──────────────────────────────────────────────────────┘
所有检查项必须全部通过（显示为绿色）才能合并：
┌──────────────────────────────────────────────────────┐
│                  MERGE GATES                         │
├──────────────────────────────────────────────────────┤
│  [ ] CI Pipeline Green                               │
│  [ ] Local Integration Tests Pass (if services)     │
│  [ ] All Tests Pass                                  │
│  [ ] Code Review Approved                            │
│  [ ] Acceptance Criteria Verified                    │
│  [ ] No Unresolved Conversations                     │
│  [ ] Branch Up to Date                               │
│  [ ] No Merge Conflicts                              │
├──────────────────────────────────────────────────────┤
│  ALL GREEN → MERGE ALLOWED                           │
│  ANY RED → MERGE BLOCKED                             │
└──────────────────────────────────────────────────────┘

Gate Details

检查项详情

1. CI Pipeline Green

1. CI流水线执行成功

bash
undefined
bash
undefined

Check all CI checks

检查所有CI检查状态

gh pr checks [PR_NUMBER]
gh pr checks [PR_NUMBER]

Expected: All passing

预期结果：全部通过

✓ build passed ✓ lint passed ✓ test passed ✓ typecheck passed ✓ security passed

**If not green:** Use `ci-monitoring` to resolve.
✓ build passed ✓ lint passed ✓ test passed ✓ typecheck passed ✓ security passed

**如果未通过：** 使用`ci-monitoring`工具解决问题。

1.5. Local Integration Tests Pass

1.5. 本地集成测试通过

CRITICAL: CI should validate, not discover. If CI found bugs, local testing was insufficient.
bash
undefined
关键提示： CI应用于验证而非发现问题。如果CI发现了bug，说明本地测试不充分。
bash
undefined

Verify services are running (if project has docker-compose)

验证服务是否运行（如果项目使用docker-compose）

docker-compose ps
docker-compose ps

Run integration tests against real services

针对真实服务运行集成测试

pnpm test:integration
pnpm test:integration

Verify migrations work

验证迁移是否正常工作

pnpm migrate

**If project has docker-compose services:**
- Services MUST be running locally
- Integration tests MUST pass against real services
- Migrations MUST apply successfully
- NOT acceptable: "unit tests with mocks pass, I'll let CI verify the real services"

**Local testing evidence must be posted to issue before PR creation.**

**Skill:** `local-service-testing`
pnpm migrate

**如果项目包含docker-compose服务：**
- 服务必须在本地运行
- 集成测试必须在真实服务环境下通过
- 迁移必须成功执行
- 不允许：“单元测试（含模拟）通过了，我让CI去验证真实服务就行”

**本地测试的证据必须在创建PR前发布到对应issue中。**

**Skill:** `local-service-testing`

2. All Tests Pass

2. 所有测试通过

bash
undefined
bash
undefined

Verify locally (CI should have done this, but verify)

本地验证（CI应该已经执行过，但建议再次验证）

pnpm test
pnpm test

Check coverage

检查测试覆盖率

pnpm test --coverage

**If failing:** Fix tests before merge.
pnpm test --coverage

**如果测试失败：** 修复测试后再合并。

3. Code Review Approved

3. 代码评审已批准

bash
undefined
bash
undefined

Check review status

检查评审状态

gh pr view [PR_NUMBER] --json reviews
gh pr view [PR_NUMBER] --json reviews

Expected: At least one approval, no changes requested

预期结果：至少有一个批准，无变更请求


**If not approved:**
- Address feedback
- Re-request review
- Wait for approval

**如果未批准：**
- 处理反馈意见
- 重新请求评审
- 等待批准

4. Acceptance Criteria Verified

4. 验收标准已验证

Check the issue:
bash
gh issue view [ISSUE_NUMBER] --json body
All acceptance criteria should be checked:
markdown
undefined
查看对应issue：
bash
gh issue view [ISSUE_NUMBER] --json body
所有验收标准应已完成检查：
markdown
undefined

Acceptance Criteria

验收标准

  • User can log in
  • Invalid credentials show error
  • Session persists
  • Logout clears session

**If not verified:** Complete verification before merge.
  • 用户可以登录
  • 无效凭证会显示错误
  • 会话可以持久化
  • 登出会清除会话

**如果未验证：** 完成验证后再合并。

5. No Unresolved Conversations

5. 无未解决的评审对话

bash
undefined
bash
undefined

Check for unresolved threads

检查是否有未解决的评审线程

gh pr view [PR_NUMBER] --json reviewThreads

All review comments should be:
- Resolved
- Or responded to with explanation

**If unresolved:** Address the feedback.
gh pr view [PR_NUMBER] --json reviewThreads

所有评审评论应：
- 已解决
- 或已给出解释性回复

**如果存在未解决项：** 处理对应的反馈意见。

6. Branch Up to Date

6. 分支已与目标分支同步

bash
undefined
bash
undefined

Check if branch is behind target

检查分支是否落后于目标分支

gh pr view [PR_NUMBER] --json mergeable,mergeStateStatus
gh pr view [PR_NUMBER] --json mergeable,mergeStateStatus

If behind, update

如果落后，进行更新

git fetch origin git rebase origin/main git push --force-with-lease

**If not up to date:** Rebase or merge target branch.
git fetch origin git rebase origin/main git push --force-with-lease

**如果未同步：** 执行变基或合并目标分支。

7. No Merge Conflicts

7. 无合并冲突

bash
undefined
bash
undefined

Check for conflicts

检查是否存在冲突

gh pr view [PR_NUMBER] --json mergeable

**If conflicts exist:** Resolve before merge.

```bash
git fetch origin
git rebase origin/main
gh pr view [PR_NUMBER] --json mergeable

**如果存在冲突：** 解决冲突后再合并。

```bash
git fetch origin
git rebase origin/main

Resolve conflicts

解决冲突

git add . git rebase --continue git push --force-with-lease
undefined
git add . git rebase --continue git push --force-with-lease
undefined

Pre-Merge Checklist

合并前检查清单

Run through this checklist before every merge:
markdown
undefined
每次合并前都要完成以下检查清单：
markdown
undefined

Pre-Merge Verification

合并前验证

CI/Tests

CI/测试

  • All CI checks passing
  • Tests pass locally
  • Coverage acceptable
  • 所有CI检查通过
  • 本地测试通过
  • 测试覆盖率符合要求

Review

评审

  • PR approved
  • All conversations resolved
  • Feedback addressed
  • PR已批准
  • 所有对话已解决
  • 反馈意见已处理

Verification

验证

  • All acceptance criteria verified
  • Verification report posted to issue
  • Issue ready to close
  • 所有验收标准已验证
  • 验证报告已发布到issue
  • Issue已准备好关闭

Branch

分支

  • Up to date with target
  • No merge conflicts
  • Commits clean
  • 已与目标分支同步
  • 无合并冲突
  • 提交记录清晰

Documentation

文档

  • PR description complete
  • Issue updated
  • Relevant docs updated
undefined
  • PR描述完整
  • Issue已更新
  • 相关文档已更新
undefined

Performing the Merge

执行合并

Once all gates are green:
所有检查项通过后：

Using GitHub CLI

使用GitHub CLI

bash
undefined
bash
undefined

Merge with squash (recommended for clean history)

使用 squash 合并（推荐，用于保持提交历史清晰）

gh pr merge [PR_NUMBER] --squash --delete-branch
gh pr merge [PR_NUMBER] --squash --delete-branch

Or merge commit

或使用普通合并提交

gh pr merge [PR_NUMBER] --merge --delete-branch
gh pr merge [PR_NUMBER] --merge --delete-branch

Or rebase

或使用变基合并

gh pr merge [PR_NUMBER] --rebase --delete-branch
undefined
gh pr merge [PR_NUMBER] --rebase --delete-branch
undefined

Merge Strategy

合并策略

StrategyWhen to Use
SquashMost PRs - creates single clean commit
MergeWhen commit history is important
RebaseWhen you want linear history without merge commit
Follow project conventions for merge strategy.
策略使用场景
Squash大多数PR - 创建单个清晰的提交
Merge当提交历史很重要时
Rebase当你想要无合并提交的线性历史时
遵循项目约定的合并策略。

Post-Merge

合并后操作

After successful merge:
合并成功后：

1. Verify Issue Closed

1. 验证Issue已关闭

bash
undefined
bash
undefined

Check issue status

检查Issue状态

gh issue view [ISSUE_NUMBER] --json state
gh issue view [ISSUE_NUMBER] --json state

Should be: "CLOSED"

预期状态: "CLOSED"

If not closed automatically, close it

如果未自动关闭，手动关闭

gh issue close [ISSUE_NUMBER] --comment "Closed by #[PR_NUMBER]"
undefined
gh issue close [ISSUE_NUMBER] --comment "Closed by #[PR_NUMBER]"
undefined

2. Update Project Status

2. 更新项目状态

bash
undefined
bash
undefined

Update GitHub Project fields

更新GitHub Project字段

Status → Done

状态 → 已完成

(Using project-status-sync)

(使用 project-status-sync)

undefined
undefined

3. Clean Up Local

3. 本地清理

bash
undefined
bash
undefined

Switch to main

切换到main分支

git checkout main
git checkout main

Pull merged changes

拉取合并后的变更

git pull origin main
git pull origin main

Delete local branch

删除本地分支

git branch -d feature/issue-123-description
git branch -d feature/issue-123-description

Prune remote tracking branches

清理远程跟踪分支

git remote prune origin
undefined
git remote prune origin
undefined

4. Verify Deployment (if applicable)

4. 验证部署（如适用）

If auto-deploy is configured:
  • Check deployment status
  • Verify feature works in deployed environment
  • Monitor for errors
如果配置了自动部署：
  • 检查部署状态
  • 验证功能在部署环境中正常工作
  • 监控是否有错误

Merge Blocked Scenarios

合并被阻止的场景

Review Not Approved

评审未批准

Cannot merge: Review required

→ Request review
→ Address feedback
→ Get approval
无法合并：需要评审

→ 请求评审
→ 处理反馈
→ 获取批准

Failing CI

CI执行失败

Cannot merge: CI checks failing

→ Use ci-monitoring skill
→ Fix failures
→ Wait for green
无法合并：CI检查失败

→ 使用ci-monitoring skill
→ 修复失败项
→ 等待CI执行成功

Branch Behind

分支落后于目标分支

Cannot merge: Branch out of date

→ git fetch origin
→ git rebase origin/main
→ Resolve conflicts
→ git push --force-with-lease
无法合并：分支已过期

→ git fetch origin
→ git rebase origin/main
→ 解决冲突
→ git push --force-with-lease

Unresolved Conversations

存在未解决的评审对话

Cannot merge: Unresolved review threads

→ Address each comment
→ Mark as resolved
→ Re-request review if needed
无法合并：存在未解决的评审线程

→ 处理每条评论
→ 标记为已解决
→ 必要时重新请求评审

Never Merge When

绝对不能合并的情况

SituationAction
Tests failingFix tests first
CI redFix CI first
Review pendingWait for review
Conflicts existResolve conflicts
Acceptance criteria not metComplete verification
Critical feedback unaddressedAddress feedback
场景操作
测试失败先修复测试
CI执行失败先修复CI
评审待处理等待评审完成
存在冲突解决冲突
验收标准未满足完成验证
关键反馈未处理处理反馈意见

Checklist

最终检查清单

Final verification before clicking merge:
  • All CI checks green
  • Local integration tests pass (if services available)
  • Local testing artifact posted to issue (if services used)
  • All tests passing
  • PR approved
  • All conversations resolved
  • Acceptance criteria verified
  • Branch up to date
  • No conflicts
  • PR documentation complete
  • Ready to close issue
点击合并前的最终验证：
  • 所有CI检查执行成功
  • 本地集成测试通过（如果有可用服务）
  • 本地测试证据已发布到issue（如果使用了服务）
  • 所有测试通过
  • PR已批准
  • 所有对话已解决
  • 验收标准已验证
  • 分支已与目标分支同步
  • 无冲突
  • PR文档完整
  • 已准备好关闭issue

Integration

集成

This skill is called by:
  • issue-driven-development
    - Step 13
This skill follows:
  • ci-monitoring
    - CI is green
  • pr-creation
    - PR exists
This skill completes:
  • The development cycle for an issue
本skill被以下流程调用：
  • issue-driven-development
    - 步骤13
本skill依赖：
  • ci-monitoring
    - CI执行成功
  • pr-creation
    - PR已存在
本skill完成：
  • 一个issue的开发周期