pre-merge

合并前验证

将更改合并到生产环境之前的全面验证工作流。

何时使用此技能

在以下情况下使用此技能：

• 创建拉取请求以供审查
• 准备将代码合并到 main/生产分支
• 需要系统化的验证清单
• 希望在代码审查前发现问题

提交前验证

提交代码前，请验证：

• 类型检查通过（根据语言选择：tsc --noEmit、mypy 等）
• 代码检查通过且没有错误（ESLint、Pylint 等）
• 所有现有测试均在本地通过
• 代码中没有遗留 console.log/debug 语句
• 代码符合项目风格指南
• 没有注释掉的代码块

按语言划分的命令

TypeScript/JavaScript：

# Type check
npx tsc --noEmit

# Lint
npm run lint
# or: pnpm lint
# or: npx eslint .

# Tests
npm test
# or: pnpm test

Python：

# Type check
mypy src/

# Lint
pylint src/
# or: flake8 src/
# or: ruff check src/

# Tests
pytest
# or: python -m pytest

Go：

# Format check
gofmt -l .

# Lint
golangci-lint run

# Tests
go test ./...

PR 前验证

创建拉取请求前，请确保：

必要信息

• 面向用户的更改已添加 changeset（如果使用 changesets）
• PR 描述完整，包含：
  • 更改摘要
  • 相关工单引用（ENG-XXX、HEL-XXX、JIRA-XXX 等）
  • UI 更改的屏幕截图（桌面、平板电脑、移动设备）
  • 已记录破坏性更改
  • 迁移指南（如果有破坏性更改）
• 为新功能添加了新测试
• 根据需要更新了文档（README、API 文档等）

安全检查清单（如果有 API 更改）

• 受保护的路由需要身份验证
• 已实现授权检查
• 使用 schema 验证输入（Zod、Pydantic 等）
• 日志中没有敏感数据
• 没有 SQL 注入漏洞
• 没有 XSS 漏洞
• 已考虑速率限制

数据库更改（如果有 schema 更改）

• 已创建迁移文件
• 已在本地数据库上测试迁移
• 已在预发布数据库上测试迁移
• 提供了向下迁移（回滚方案）
• 没有未附带迁移指南的破坏性更改
• 已记录 schema 更改

UI 更改（如适用）

• 已附上屏幕截图：
  • 桌面视图（1920x1080）
  • 平板电脑视图（768x1024）
  • 移动设备视图（375x667）
• 已验证响应式行为
• 已检查无障碍功能（键盘导航、屏幕阅读器）
• 已实现加载状态
• 已实现错误状态

合并前验证

合并到 main 分支前，请确认：

CI/CD 检查

• 所有 CI 检查均通过（代码检查、类型检查、测试、构建）
• 至少一名审查者已批准代码审查
• 更改的文件中没有 TypeScript 错误
• 与目标分支没有合并冲突
• 构建成功且没有警告

功能验证

• 数据库迁移成功运行（如适用）
• 现有功能没有回归
• 性能基准在可接受范围内
• 已完成关键路径的手动测试

文档

• 已更新 CHANGELOG.md（如有使用）
• 已更新 API 文档（如果有 API 更改）
• 已更新 README（如果设置或用法有更改）
• 已提供迁移指南（如果有破坏性更改）

PR 描述模板

使用此模板撰写完整的 PR 描述：

## Summary
[Brief description of what this PR does]

## Related Tickets
- Fixes #123
- Closes ENG-456
- Related to HEL-789

## Changes
- [ ] Feature: [Description]
- [ ] Bug Fix: [Description]
- [ ] Refactor: [Description]
- [ ] Documentation: [Description]

## Testing
### Unit Tests
- Added tests for [feature/function]
- Coverage: X%

### Manual Testing
- [ ] Tested on desktop (Chrome, Firefox, Safari)
- [ ] Tested on mobile (iOS Safari, Android Chrome)
- [ ] Tested edge cases: [list specific cases]

## Screenshots
### Desktop
![Desktop view](screenshot-url)

### Tablet
![Tablet view](screenshot-url)

### Mobile
![Mobile view](screenshot-url)

## Breaking Changes
[List any breaking changes or write "None"]

### Migration Guide
[If breaking changes, provide migration steps]

## Performance Impact
[Describe any performance implications or write "No impact"]

## Security Considerations
[Describe security implications or write "No security impact"]

## Rollback Plan
[Describe how to rollback if issues occur]

## Deployment Notes
[Any special deployment considerations or write "Standard deployment"]

应避免的常见问题

提交前

• ❌ 提交测试未通过的代码
• ❌ 遗留 console.log/debug 语句
• ❌ 未运行类型检查器就提交
• ❌ 提交大段注释掉的代码

PR 前

• ❌ 创建 PR 却没有描述
• ❌ UI 更改缺少屏幕截图
• ❌ 未关联相关工单
• ❌ 未记录破坏性更改
• ❌ 新代码缺少测试覆盖

合并前

• ❌ CI 检查未通过就合并
• ❌ 未经代码审查批准就合并
• ❌ 存在合并冲突时合并
• ❌ 未测试迁移就合并
• ❌ 未考虑回滚方案就合并

快速验证脚本

创建提交前验证脚本：

JavaScript/TypeScript（pre-commit.sh）：

#!/bin/bash
set -e

echo "Running type check..."
npx tsc --noEmit

echo "Running linter..."
npm run lint

echo "Running tests..."
npm test -- --run

echo "✅ All checks passed!"

Python（pre-commit.sh）：

#!/bin/bash
set -e

echo "Running type check..."
mypy src/

echo "Running linter..."
pylint src/

echo "Running tests..."
pytest

echo "✅ All checks passed!"

设置为可执行：

chmod +x pre-commit.sh

使用 Git Hooks 自动化

设置自动提交前检查：

使用 Husky（JavaScript/TypeScript）

npm install --save-dev husky
npx husky install
npx husky add .husky/pre-commit "npm run lint && npm test"

使用 pre-commit（Python）

创建 .pre-commit-config.yaml：

repos:
  - repo: local
    hooks:
      - id: type-check
        name: Type Check
        entry: mypy src/
        language: system
        pass_filenames: false
      - id: lint
        name: Lint
        entry: pylint src/
        language: system
        pass_filenames: false
      - id: test
        name: Test
        entry: pytest
        language: system
        pass_filenames: false

安装钩子：

pre-commit install

成功标准

提交前成功标准

• ✅ 所有本地检查均通过
• ✅ 代码格式正确
• ✅ 不再有调试语句
• ✅ 本地测试通过

创建 PR 前成功标准

• ✅ PR 描述全面
• ✅ 已包含所有必需信息
• ✅ 已附上截图（如果有 UI 变更）
• ✅ 已记录破坏性变更

合并前成功标准

• ✅ CI 流水线状态为绿色
• ✅ 代码审查已通过
• ✅ 与目标分支无冲突
• ✅ 已完成手动测试

相关技能

• universal-verification-screenshot - UI 变更的截图验证
• universal-verification-bug-fix - Bug 修复验证工作流
• toolchains-universal-security-api-review - API 安全测试
• universal-collaboration-git-workflow - Git 工作流最佳实践