open-source-contributions

开源贡献技能

版本：1.1.0 | 最近验证：2025-11-06 | 生产环境测试：✅

---

概述

为开源项目做贡献，需要了解礼仪、惯例以及维护者的期望。这项技能有助于创建专业且便于维护者审核的拉取请求，同时避免常见错误，以免浪费时间或导致请求被拒绝。

重点：清理个人开发文件、撰写合适的 PR 描述、遵循项目惯例并进行专业沟通。

---

何时使用这项技能

在以下情况下使用这项技能：

• 为公开仓库创建拉取请求
• 为社区开源项目做贡献
• 向自己并不维护的项目提交代码
• 首次为新项目做贡献
• 希望提高 PR 的接受率
• 需要有关 PR 最佳实践的指导

以下短语会自动触发：“submit PR to”、“contribute to”、“pull request for”、“open source contribution”

---

拉取请求中不应包含的内容

个人开发文件（绝不要包含）

计划和笔记文档：

❌ SESSION.md              # Session tracking notes
❌ NOTES.md                # Personal development notes
❌ TODO.md                 # Personal todo lists
❌ planning/*              # Planning documents directory
❌ IMPLEMENTATION_PHASES.md # Project planning
❌ DATABASE_SCHEMA.md      # Unless adding new schema to project
❌ ARCHITECTURE.md         # Unless documenting new architecture
❌ SCRATCH.md              # Temporary notes
❌ DEBUGGING.md            # Debugging notes
❌ research-logs/*         # Research notes

截图和视觉素材：

❌ screenshots/debug-*.png     # Debugging screenshots
❌ screenshots/test-*.png      # Testing screenshots
❌ screenshot-*.png            # Ad-hoc screenshots
❌ screen-recording-*.mp4      # Screen recordings
❌ before-after-local.png      # Local comparison images

✅ screenshots/feature-demo.png   # IF demonstrating feature in PR description
✅ docs/assets/ui-example.png     # IF part of documentation update

测试文件（视情况而定）：

❌ test-manual.js          # Manual testing scripts
❌ test-debug.ts           # Debugging test files
❌ quick-test.py           # Quick validation scripts
❌ scratch-test.sh         # Temporary test scripts
❌ example-local.json      # Local test data

✅ tests/feature.test.js   # Proper test suite additions
✅ tests/fixtures/data.json # Required test fixtures
✅ __tests__/component.tsx  # Component tests

构建和依赖项：

❌ node_modules/           # Dependencies (in .gitignore)
❌ dist/                   # Build output (in .gitignore)
❌ build/                  # Build artifacts (in .gitignore)
❌ .cache/                 # Cache files (in .gitignore)
❌ package-lock.json       # Unless explicitly required by project
❌ yarn.lock               # Unless explicitly required by project

IDE 和操作系统文件：

❌ .vscode/                # VS Code settings
❌ .idea/                  # IntelliJ settings
❌ .DS_Store               # macOS file system
❌ Thumbs.db               # Windows thumbnails
❌ *.swp, *.swo            # Vim swap files
❌ *~                      # Editor backup files

机密和敏感数据：

❌ .env                    # Environment variables (NEVER!)
❌ .env.local              # Local environment config
❌ config/local.json       # Local configuration
❌ credentials.json        # Credentials (NEVER!)
❌ *.key, *.pem            # Private keys (NEVER!)
❌ secrets/*               # Secrets directory (NEVER!)

临时文件和调试文件：

❌ temp/*                  # Temporary files
❌ tmp/*                   # Temporary directory
❌ debug.log               # Debug logs
❌ *.log                   # Log files
❌ dump.sql                # Database dumps
❌ core                    # Core dumps
❌ *.prof                  # Profiling output

应包含的内容

✅ Source code changes      # The actual feature/fix
✅ Tests for changes        # Required tests for new code
✅ Documentation updates    # README, API docs, inline comments
✅ Configuration changes    # If part of the feature
✅ Migration scripts        # If needed for the feature
✅ Package.json updates     # If adding/removing dependencies
✅ Schema changes           # If part of feature (with migrations)
✅ CI/CD updates            # If needed for new workflows

---

PR 提交前清理流程

第 1 步：运行 PR 提交前检查脚本

使用随附的 scripts/pre-pr-check.sh 扫描文件：

./scripts/pre-pr-check.sh

检查内容：

• 个人文档（SESSION.md、planning/*、NOTES.md）
• PR 描述中未引用的截图
• 临时测试文件
• 大文件（>1MB）
• 文件内容中可能存在的机密
• PR 大小（超过 400 行时发出警告）
• 未提交的更改

第 2 步：检查 Git 状态

git status
git diff --stat

问问自己：

• 每项文件更改对于此功能或修复是否都必不可少？
• 是否有任何无关更改？
• 是否有开发过程中添加但并不需要的文件？

第 3 步：清理个人文件

手动删除：

git rm --cached SESSION.md
git rm --cached -r planning/
git rm --cached screenshots/debug-*.png
git rm --cached test-manual.js

或使用清理脚本：

./scripts/clean-branch.sh

第 4 步：更新 .gitignore

将个人文件匹配规则添加到 .git/info/exclude（仅影响你自己的工作副本）：

# Personal development artifacts
SESSION.md
NOTES.md
TODO.md
planning/
screenshots/debug-*.png
test-manual.*
scratch.*

---

撰写有效的 PR 描述

使用 What/Why/How 结构

模板（参见 references/pr-template.md）：

## What?
[Brief description of what this PR does]

## Why?
[Explain the reasoning, business value, or problem being solved]

## How?
[Describe the implementation approach and key decisions]

## Testing
[Step-by-step instructions for reviewers to test]

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CI passing
- [ ] Breaking changes documented

## Related Issues
Closes #123
Relates to #456

优秀的 PR 描述示例

## What?
Add OAuth2 authentication support for Google and GitHub providers

## Why?
Users have requested social login to reduce friction during signup.
This implements Key Result 2 of Q4 OKR1.

## How?
- Implemented OAuth2 flow using passport.js
- Added provider configuration in environment variables
- Created callback routes for each provider
- Updated user model to link social accounts

## Testing
1. Set up OAuth apps in Google/GitHub developer consoles
2. Add credentials to `.env` (see `.env.example`)
3. Run `npm start`
4. Click "Login with Google" and verify flow
5. Verify user profile merges correctly

## Breaking Changes
None - this is additive functionality

## Related Issues
Closes #234
Relates to #156 (social login epic)

标题：遵循 Conventional Commits 规范

格式：<type>(<scope>): <description>

类型：

• feat: - 新功能
• fix: - 修复错误
• docs: - 仅文档
• style: - 格式调整（不更改代码）
• refactor: - 重构代码（不更改行为）
• perf: - 性能改进
• test: - 添加或更新测试
• build: - 构建系统更改
• ci: - CI 配置更改
• chore: - 其他更改（不更改 src/test）

示例：

✅ feat(auth): add OAuth2 support for Google and GitHub
✅ fix(api): resolve memory leak in worker shutdown
✅ docs(readme): update installation instructions for v2.0
✅ refactor(utils): extract validation logic to separate module

❌ Fixed stuff
❌ Updates
❌ Working on authentication (too vague)

---

提交消息最佳实践

结构

完整指南请参见 references/commit-message-guide.md。

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

[optional body]

[optional footer]

主题行规则：

• 最多 50 个字符
• 使用祈使语气（“Add”，而不是“Added”）
• 首字母大写
• 末尾不加句号
• 描述更改了什么

正文规则（可选）：

• 每行 72 个字符
• 说明原因（代码展示了更改内容）
• 与主题行之间空一行

页脚（可选）：

• 引用问题：Closes #123
• 注明不兼容的更改：BREAKING CHANGE: ...

示例

正确：

fix: prevent race condition in cache invalidation

The cache invalidation logic wasn't thread-safe, causing
occasional race conditions when multiple workers tried to
invalidate the same key simultaneously.

Added mutex locks around the critical section and tests
to verify thread-safety.

Fixes #456

错误：

Fixed bug                          # Too vague
WIP                               # Not descriptive
asdf                              # Meaningless
Updated auth.js                   # Describes file, not change
Fixed the issue with the thing    # No specifics

---

PR 大小最佳实践

理想大小

基于研究的指南：

• 理想：50 行代码
• 良好：少于 200 行
• 上限：400 行
• 超过 400 行：缺陷检测能力会显著下降

小型 PR 的重要性：

• 审核更快（维护者可以一次完成审核）
• 更容易发现错误
• 需要时更容易回滚
• 减少合并冲突
• 讨论更聚焦

如何让 PR 保持精简

1. 一项更改 = 一个 PR

❌ BAD: Refactor auth module + add OAuth + fix bug + update docs (800 lines)

✅ GOOD:
  PR #1: Refactor auth module (150 lines)
  PR #2: Add OAuth support (200 lines)
  PR #3: Fix authentication bug (50 lines)
  PR #4: Update authentication docs (80 lines)

2. 将重构与功能开发分开

❌ BAD: Add feature X + refactor related code (500 lines)

✅ GOOD:
  PR #1: Refactor to prepare for feature X (200 lines)
  PR #2: Add feature X (150 lines)

3. 使用功能开关 将未完成的功能置于开关之后发布，尽早且频繁地合并：

if (featureFlags.newAuth) {
  // New OAuth flow (incomplete but behind flag)
} else {
  // Existing flow
}

4. 按层拆分

For "User Authentication" feature:
  PR #1: Database schema + migrations (100 lines)
  PR #2: API endpoints (150 lines)
  PR #3: Frontend components (200 lines)
  PR #4: Tests + documentation (150 lines)

何时可以接受大型 PR

• 项目初始搭建
• 生成的代码（需明确标注）
• 无法拆分的大型重构（在说明中解释原因）
• 文档重写
• 依赖项更新（自动化）

如果无法避免：在 PR 描述中添加清晰的章节标题，引导审查。

---

遵循项目规范

步骤 1：阅读 CONTRIBUTING.md

务必先读这个文件——它是项目的准则。常见位置：

• /CONTRIBUTING.md
• /.github/CONTRIBUTING.md
• /docs/CONTRIBUTING.md

需要检查的关键章节：

• 开发环境设置
• 测试要求
• 代码风格指南
• 提交消息格式
• PR 流程
• 审查预期

提示：在仓库 URL 后添加 /contribute，即可查找适合新手的问题。

步骤 2：查看风格指南

需要查找的文件：

• .eslintrc、.eslintrc.js（JavaScript/TypeScript 代码检查）
• .prettierrc（代码格式化）
• .editorconfig（编辑器设置）
• STYLE.md（风格指南文档）
• rustfmt.toml（Rust 格式化）
• pyproject.toml（Python 格式化）

提交前运行格式化工具：

npm run lint                # Check for style issues
npm run lint:fix            # Auto-fix style issues
npm run format              # Format code (Prettier, Black, etc.)

步骤 3：遵循现有模式

查看近期已合并的 PR：

• 文件是如何组织的？
• 使用了哪些命名规范？
• 注释有多详细？
• 有哪些测试模式？
• 导入项是如何排序的？

黄金法则：“按照项目维护者期望的方式做事。”

步骤 4：测试要求

提交前：

# Run full test suite
npm test                    # Node projects
cargo test                  # Rust projects
pytest                      # Python projects
go test ./...               # Go projects

# Check coverage (if required)
npm run test:coverage

# Run linters
npm run lint

# Build the project
npm run build

切勿提交包含以下问题的 PR：

• 测试未通过
• 代码检查未通过
• 构建错误
• 新代码未经测试（如果要求编写测试）

---

沟通最佳实践

开始工作前

在问题下评论：

Hi! I'd like to work on this issue. My approach would be to:
1. [Brief outline of approach]
2. [Key implementation detail]

Does this sound good? Any guidance before I start?

这样做的意义：

• 避免重复劳动
• 尽早获得对方案的反馈
• 表明尊重维护者的时间
• 建立沟通渠道

对于重要更改，先等待确认再投入时间。

撰写 PR 评论

提交时：

@maintainer I've implemented the feature as discussed in #123.
I went with approach A instead of B because [reason].

Ready for review when you have time. Happy to make changes!

回复反馈时：

Good catch! I've updated this in commit abc1234.

I considered that approach, but went with X because Y.
Happy to discuss alternatives if you prefer a different direction.

Could you elaborate on what you mean by Z?
I want to make sure I understand correctly.

回复审查意见

关键原则：

1. 逐条回复所有意见——哪怕只回复“已完成”或“已知悉”
2. 切勿在愤怒时回复——有需要时先离开，冷静后再回复
3. 使用 GitHub 的审查工具：
   • 处理完后将对话标记为已解决
   • 更改后请求重新审查
   • 使用“建议”功能快速修复
4. 讨论保持切题——将旁枝话题转到其他地方讨论
5. 心怀感激——审查很有价值，也很耗费时间

回复模板：

• 已实现：“好主意！已在 [commit hash] 中实现”
• 提问：“谢谢提问——我这样做是因为 Y。你怎么看？”
• 不同意：“我理解你的看法。我选择了 X，因为 Y。如果你很在意，我也愿意考虑其他方案。”
• 需要澄清：“能否请你解释一下 Z 是什么意思？”

处理 PR 被拒

心态建设：

• 这是一次学习经历，不是个人失败
• 被拒很正常，每个人都会遇到
• 项目的愿景可能与你的方案不同

应对步骤：

1. 寻求澄清——礼貌地询问 PR 被拒的原因
2. 仔细查看反馈——找出具体问题
3. 从中学习——下次你会做出哪些不同的选择？
4. 可选方案：
   • 根据反馈返工
   • Fork 并维护自己的更改
   • 转而参与其他贡献

不要这样做：

• 不要继续在已拒绝的 PR 下评论
• 不要往心里去
• 不要激烈争辩
• 不要彻底放弃该项目（除非它确实不适合你）

耐心等待（但也要知道何时提醒）

维护者通常是志愿者：

• 他们有日常工作、家庭和自己的生活
• 他们可能正在审查数十个 PR
• 他们可能正在处理复杂的项目问题

时间预期：

• 小型 PR：1-7 天
• 大型 PR：1-2 周
• 复杂/有争议的 PR：数周到数月

何时提醒：

• 小型 PR 等待 1 周后
• 大型 PR 等待 2 周后
• CI 因外部变更而失败时（需要 rebase）

如何提醒：

Hi! Just wanted to gently ping this PR.
No rush at all, just making sure it's on your radar.
Happy to answer any questions or make changes!

---

令维护者头疼的常见错误

16 个常见错误

详细说明请参阅“关键工作流规则”部分中的规则 1-3

1. 不阅读 CONTRIBUTING.md

• 影响：白费功夫、PR 被拒、维护者感到沮丧
• 改进：务必先阅读此文件，并严格遵循其中的说明

2. 提交个人开发过程中的产物

• 影响：PR 杂乱无章、暴露内部工作流、显得不专业
• 改进：使用 PR 提交前检查脚本，在提交前清理产物
• 示例：SESSION.md、planning/*、截图、临时测试文件

3. 提交大规模 Pull Request

• 影响：审查负担过重、更难发现错误、延误合并
• 改进：拆分成更小的 PR（理想情况下少于 200 行）

4. 提交前不测试代码（违反规则 2）

• 影响：CI 失败、生产环境出现错误、维护者不得不修复、信任受损
• 改进：参阅规则 2——运行完整测试套件、手动测试、留存证据（截图/视频），并确认 CI 能够通过

5. 处理已分配给他人的问题

• 影响：重复劳动、双方都浪费时间
• 改进：检查问题的分配情况，并留言认领任务

6. 不先讨论就进行改动（针对大型改动）

• 影响：不受欢迎的功能、PR 被拒、开发时间白费
• 改进：编码前先创建问题或留言讨论

7. 缺乏耐心或不回应

• 影响：PR 停滞、维护者转而处理其他事务、贡献不了了之
• 改进：及时回应，同时保持耐心；等待 1-2 周后再礼貌提醒

8. 不更新文档

• 影响：用户和开发者会因缺少改动说明而感到困惑
• 改进：根据需要更新 README、API 文档和内联注释

9. 忽视代码风格规范

• 影响：代码库杂乱，维护者不得不修正格式
• 改进：使用项目的 linter/formatter，并遵循现有风格

10. 忽视 CI 失败

• 影响：无法合并、阻碍进度、维护者不得不调查原因
• 改进：监控 CI，立即修复失败；遇到困难时寻求帮助

11. 包含无关改动（违反规则 3）

• 影响：难以审查、更难回滚、范围蔓延、Git 历史令人困惑
• 改进：参阅规则 3——一个 PR 只对应一个功能。保持专注，将无关改动拆分到不同分支/PR 中

12. 未正确关联问题

• 影响：上下文丢失、需要手动关闭问题、更难追踪
• 改进：在 PR 描述中使用 “Closes #123” 或 “Fixes #456”

13. 提交密钥或敏感数据

• 影响：安全风险、需要紧急响应、可能导致数据泄露
• 改进：使用 .gitignore，扫描密钥，切勿提交 .env 文件

14. 未事先通知就强制推送

• 影响：破坏审查者的本地副本、导致评论丢失
• 改进：审查开始后尽量避免强制推送；必要时提前通知

15. 未在本地运行构建/测试

• 影响：显而易见的问题导致 CI 失败、浪费 CI 资源
• 改进：推送前务必运行 npm run build 和 npm test

16. 直接在 main/master 分支上工作（违反规则 1）

• 影响：Git 历史杂乱、与上游冲突、无法同时处理多个功能、难以同步 Fork
• 改进：参阅规则 1——务必创建功能分支（git checkout -b feature/my-feature），绝不要提交到 main

---

GitHub 专属最佳实践

Fork 工作流（开源项目的标准做法）

初始设置：

# 1. Fork repository on GitHub (click Fork button)

# 2. Clone YOUR fork
git clone https://github.com/YOUR-USERNAME/project-name.git
cd project-name

# 3. Add upstream remote
git remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git

# 4. Verify remotes
git remote -v
# origin    https://github.com/YOUR-USERNAME/project-name.git (fetch)
# origin    https://github.com/YOUR-USERNAME/project-name.git (push)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (fetch)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (push)

创建功能分支：

# NEVER work on main/master directly!
git checkout -b feature/add-oauth-support

# Make changes...
git add .
git commit -m "feat(auth): add OAuth2 support"

# Push to YOUR fork
git push origin feature/add-oauth-support

保持 Fork 同步：

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

---

关键工作流规则（绝不跳过）

规则 1：始终在功能分支上工作

# ❌ NEVER DO THIS
git checkout main
# make changes directly on main
git commit -m "add feature"  # BAD!

# ✅ ALWAYS DO THIS
git checkout main
git pull upstream main  # Sync first
git checkout -b feature/add-oauth-support  # Descriptive branch name
# make changes on feature branch
git commit -m "feat(auth): add OAuth support"

为什么这很重要：

• 保持 main 分支整洁，并与上游同步
• 支持同时处理多个功能
• 方便放弃或重新开始工作
• 大多数开源项目都要求这样做
• 避免冲突和混乱的 git 历史记录

分支命名约定：

feature/descriptive-name    # New features
fix/issue-123               # Bug fixes
docs/update-readme          # Documentation
refactor/extract-utils      # Refactoring
test/add-unit-tests         # Test additions

---

规则 2：提交 PR 前充分测试

提交 PR 前，务必完成以下事项：

1. 在本地运行完整测试套件：

   npm test              # Node.js
   cargo test            # Rust
   pytest                # Python
   go test ./...         # Go
   

2. 手动测试（亲自验证）：

   • 运行应用程序
   • 测试添加的特定功能
   • 测试边界情况和错误条件
   • 确认功能按预期运行

3. 收集证据（针对视觉/UI 更改）：

   • 截取展示功能正常运行的屏幕截图
   • 如果功能较复杂，录制一段简短的演示视频
   • 在 PR 描述中附上证据，展示功能效果

4. 确认 CI 能够通过：

   npm run lint          # Linting
   npm run build         # Build succeeds
   npm run type-check    # TypeScript checks
   

新增 OAuth 功能的测试清单示例：

## Testing Performed

### Automated Tests
- ✅ All existing tests pass
- ✅ Added 12 new tests for OAuth flow
- ✅ Coverage increased from 85% to 87%

### Manual Testing
- ✅ Tested Google OAuth flow end-to-end
- ✅ Tested GitHub OAuth flow end-to-end
- ✅ Verified error handling (invalid tokens, network failures)
- ✅ Confirmed user profile merging works correctly
- ✅ Tested on Chrome, Firefox, Safari

### Evidence
See screenshots below showing successful login flow.

为什么这很重要：

• 避免 CI 失败，减少维护者的时间浪费
• 体现你对代码质量的重视
• 证明功能确实可用
• 建立维护者对你的信任
• 在评审前发现错误

PR 描述中的屏幕截图：

✅ Include: Working feature demonstration
✅ Include: Before/after comparisons for changes
✅ Include: Error state handling

❌ Don't include: Debug screenshots in code commits
❌ Don't include: Personal testing screenshots in repo
❌ Don't include: Unrelated screenshots

Location: Add to PR description on GitHub, NOT as files in commits

---

规则 3：保持 PR 聚焦且连贯

一个 PR = 一个功能/修复

✅ GOOD: Single PR adding OAuth support
  - OAuth provider configuration
  - Login/callback routes
  - User model updates
  - Tests for OAuth flow
  - Documentation for setup

❌ BAD: PR with multiple unrelated changes
  - OAuth support
  - + Unrelated bug fix in validation
  - + Random formatting changes
  - + Update to README for different feature

PR 连贯的重要性：

• 更容易评审和理解
• 可以独立合并或拒绝
• 发现问题时更容易回滚
• 加快评审周期
• 保持 git 历史记录清晰

如何让 PR 保持聚焦：

1. 编码前先规划：

   • 这个 PR 要做的唯一一件事是什么？
   • 这个功能必须修改哪些文件？
   • 需要的最小更改集是什么？

2. 开发过程中：

   • 如果发现无关的错误，请创建单独的分支
   • 如果想顺手修复格式问题，请通过单独的 PR 处理
   • 始终聚焦于单一目标

3. 提交前：

   • 检查你的更改：git diff
   • 自问：“这个文件的更改对这个功能是必需的吗？”
   • 将无关的更改移至暂存区：git stash

4. 规模建议：

   • 理想：更改少于 200 行
   • 可接受：200–400 行
   • 较大：400–800 行（需要说明理由）
   • 过大：超过 800 行（应拆分）

拆分大型功能：

如果功能本身规模较大，请分阶段完成：

PR #1: Database schema and models
PR #2: API endpoints
PR #3: Frontend components
PR #4: Integration and tests

每个 PR 都应：

• 基于前一个 PR 构建
• 可独立评审
• 添加可用功能（或明确标记为 WIP/基础性工作）

处理意外扩大的范围：

# You added OAuth + accidentally fixed a bug
# Split them into separate commits and PRs:

# 1. Create bug fix branch from main
git checkout main
git checkout -b fix/validation-bug

# 2. Cherry-pick just the bug fix commits
git cherry-pick <commit-hash-of-bug-fix>

# 3. Submit bug fix PR separately
git push origin fix/validation-bug

# 4. Continue with OAuth PR
git checkout feature/add-oauth-support
# Remove bug fix commits if needed
git rebase -i main

---

使用草稿 PR

适用情况：

• 代码仍在开发中，尚未准备好接受评审
• 希望尽早获得对实现方案的反馈
• 开始讨论实现方式
• 分享未完成的代码以便协作

优点：

• 避免意外合并
• 不会触发评审者通知
• 明确表明“尚未准备就绪”

创建草稿 PR：

gh pr create --draft --title "WIP: Add OAuth support"

在以下情况下标记为准备就绪：

• 代码已完成并经过测试
• CI 已通过
• 文档已更新
• 已准备好接受正式评审

gh pr ready

正确关联 Issue

自动关闭关键词（用于 PR 描述或提交信息）：

Closes #123
Fixes #456
Resolves #789

# Also works:
Close #123
Fix #123
Resolve #123

# Case insensitive:
CLOSES #123
fixes #123

# Multiple issues:
Fixes #10, closes #20, resolves #30

# Cross-repo:
Fixes owner/repo#123

重要：只有在合并到 DEFAULT 分支（通常是 main）时才会生效。

使用 GitHub CLI

高效创建 PR：

# Interactive (prompts for title/body)
gh pr create

# Auto-fill from commits
gh pr create --fill

# Complete non-interactive
gh pr create \
  --title "feat(auth): add OAuth support" \
  --body "$(cat <<'EOF'
## What?
Add OAuth2 authentication

## Why?
User request for social login

## Testing
1. Set up OAuth apps
2. Run npm start
3. Test login flow
EOF
)"

# With reviewers
gh pr create --reviewer username1,username2

# Draft PR
gh pr create --draft

其他实用命令：

gh pr status              # See your PRs
gh pr checks              # View CI status
gh pr view                # View current PR
gh pr diff                # See PR diff
gh pr ready               # Mark draft as ready
gh pr merge               # Merge PR (when approved)

---

提交前检查清单

提交任何拉取请求前，请使用此检查清单（参见 references/pr-checklist.md）。

贡献前

• 仔细阅读 CONTRIBUTING.md
• 如有 CODE_OF_CONDUCT.md，请阅读
• 确认是否应先创建 issue
• 在 issue 中留言认领工作
• 维护者已确认这项工作（针对重大更改）
• 已 Fork 仓库（如果没有写入权限）
• 已设置 upstream 远程仓库
• 已创建功能分支（绝不要在 main 上工作）

开发

关键工作流规则（详见上文）：

• 规则 1：在功能分支上工作（而不是 main/master）
• 规则 2：经过充分测试，并准备好相关证据
• 规则 3：PR 应聚焦于单一功能或修复

代码质量：

• 代码遵循项目风格指南
• 已运行代码检查工具和格式化工具
• 所有测试在本地均通过（npm test、cargo test 等）
• 为新功能添加了测试
• 已进行手动测试（运行应用并测试功能）
• 已收集证据（视觉改动需提供截图或视频）
• 已更新相关文档
• 提交信息遵循约定
• 与基础分支没有合并冲突
• 项目已成功构建（npm run build 等）

清理

• 已运行 PR 提交前检查脚本（./scripts/pre-pr-check.sh）
• 已移除个人文件：
  • 没有 SESSION.md 或笔记文件
  • 没有 planning/* 文档
  • 没有调试截图
  • 没有临时测试文件
  • 没有个人工作流文件
• 已检查 git status，确认没有不需要的文件
• 没有机密或敏感数据
• 没有 IDE 或操作系统专属文件
• 没有构建产物或依赖项

PR 质量

• PR 聚焦于一个改动或问题
• PR 大小适中（理想情况下少于 200 行，最多不超过 400 行）
• 没有包含无关改动
• 已检查自己的差异，确认没有意外改动
• 标题遵循约定（Conventional Commits）
• 描述采用 What/Why/How 结构
• 包含测试说明
• 链接到相关问题（Closes #123）
• 视觉改动附有截图（用于展示功能时）
• 已注明破坏性改动
• 审阅者无需提问即可理解

提交

• CI 和检查均已通过
• 已推送到 fork 上的功能分支
• 已创建 PR，并附上规范的描述
• 已指定标签（如获准）
• 已请求审阅者（如已知）
• 已关联项目或里程碑（如适用）

提交后

• 持续关注 CI 是否失败
• 及时回应反馈
• 及时处理审阅意见
• 将对话标记为已解决
• 修改后请求重新审阅
• 感谢审阅者
• 等待时保持耐心

---

快速命令参考

Git 工作流

# Setup
git clone https://github.com/YOUR-USERNAME/project.git
git remote add upstream https://github.com/ORIGINAL/project.git

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push to your fork
git push origin feature/my-feature

# Keep fork synced
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Rebase feature branch if needed
git checkout feature/my-feature
git rebase main
git push origin feature/my-feature --force-with-lease

GitHub CLI

# Create PR
gh pr create --title "feat: ..." --body "..."

# Check status
gh pr status
gh pr checks

# View PR
gh pr view
gh pr diff

# Manage PR
gh pr ready              # Mark draft as ready
gh pr review --approve   # Approve (if reviewer)
gh pr merge             # Merge (when approved)

PR 提交前验证

# Run checks
npm run lint
npm test
npm run build

# Use skill script
./scripts/pre-pr-check.sh

# Check git status
git status
git diff --stat

# Review changes
git diff
git log --oneline -5

---

示例

请参阅随附示例，查看完整的前后对比：

• assets/good-pr-example.md - 结构良好的 PR
• assets/bad-pr-example.md - 应避免的常见错误

---

要点总结

1. 清理 PR - 提交前移除所有个人开发文件
2. 阅读 CONTRIBUTING.md - 务必先阅读，并严格遵循说明
3. 保持 PR 小巧 - 理想情况下少于 200 行，每个 PR 只做一项改动
4. 全面测试 - 提交前在本地测试，并立即修复 CI 失败
5. 遵循约定 - 风格、提交、测试和文档均须遵循约定
6. 妥善沟通 - 保持尊重、积极回应、耐心和专业
7. 关联问题 - 使用“Closes #123”自动关闭相关问题
8. 保持耐心 - 维护者往往是时间有限的志愿者
9. 从反馈中学习 - 每次审阅都是学习机会
10. 使用自动化 - 脚本、模板和清单有助于避免错误

---

资源

内置资源：

• scripts/pre-pr-check.sh - 提交前扫描各类产物
• scripts/clean-branch.sh - 清理常见的个人文件
• references/pr-template.md - PR 描述模板
• references/pr-checklist.md - 完整的提交前检查清单
• references/commit-message-guide.md - 约定式提交指南
• references/files-to-exclude.md - 全面的排除列表
• assets/good-pr-example.md - 结构良好的 PR 示例
• assets/bad-pr-example.md - 需要避免的常见错误

外部资源：

• GitHub 开源指南：https://opensource.guide/
• 如何贡献：https://opensource.guide/how-to-contribute/
• 约定式提交：https://www.conventionalcommits.org/
• GitHub CLI：https://cli.github.com/manual/

---

经过生产环境测试：✅ 基于真实的开源贡献和维护者反馈

Token 效率：与通过反复试错学习相比，节省约 70%

预防的错误：记录了 15 个常见错误及其解决方案

上次验证时间：2025-11-05