contributor

贡献者

自动化开源贡献工作流，帮助你从 GitHub 仓库 URL 一路完成贡献，直到 PR 合并，并内置防护措施，避免常见的贡献失败情况。

为什么需要此技能

开源贡献失败的原因往往可以预见：在错误的层级修复问题（维护者更倾向于在上游修复，因此关闭你的 PR）、与其他贡献者冲突、不遵循项目惯例，或对简单修复过度设计。此工作流通过系统化的预检查，避免这些问题。

阶段 1：前期调查

编写任何代码之前，先收集项目及其贡献情况的相关信息。

1.1 确定目标

向用户询问：

• GitHub 仓库 URL（例如，pydantic/pydantic-ai）
• 用于提交的 GitHub 用户名和电子邮件
• 想要处理的具体问题（或者请用户扫描可处理的问题）

1.2 扫描可处理的问题

使用 gh CLI 查找值得参与的问题：

# Get open issues with metadata
gh issue list -R <owner>/<repo> --state open --limit 50 \
  --json number,title,labels,assignees,comments

# Check for competing PRs on each candidate
gh pr list -R <owner>/<repo> --state open \
  --search "<issue_number> in:title,body"

筛选标准（按顺序应用）：

1. 无指派人
2. 没有已在修复该问题的未关闭 PR（同时检查关联的 PR 和标题／正文搜索结果）
3. 竞争中的 PR 少于 5 个
4. 优先选择带有以下标签的问题：bug、good first issue、help wanted
5. 优先选择维护者评论中建议了修复方向的问题

1.3 深入阅读问题评论

阅读每个候选问题的完整评论串：

gh issue view <number> -R <owner>/<repo> --json body,comments

提取以下信息：

• 维护者的修复方向：他们更倾向于在此处修复，还是在上游依赖中修复？
• 建议的方法：是否提供了代码提示、文件引用或架构指导？
• 阻碍因素：是否正在等待另一个 PR 或版本发布？
• 参与者：即使没有指派人，也可能有人评论说“我来处理”

1.4 检查是否被引导到上游修复

这是最常见的失败原因。在着手修复之前：

# Check if maintainers reference another repo
gh issue view <number> -R <owner>/<repo> --json comments \
  | grep -i "upstream\|genai-prices\|separate repo\|other repo"

# Check related repos for recent PRs mentioning this issue
gh pr list -R <owner>/<related-repo> --state open --limit 10 \
  --json title,body | grep -i "<issue_number>\|<issue_keywords>"

如果有任何迹象表明修复应在其他地方进行，请停止并先询问用户。

阶段 2：事先沟通

不要毫无预告地提交 PR。务必先说明你的意图。

2.1 在问题下发布解决方案概要

编写代码之前，先在问题下评论，说明你提出的方法。这有两个目的：礼貌地认领任务，并让维护者有机会在你白费功夫之前引导你调整方向。

模板：

Hi, I've been looking into this and traced the root cause to <X>.

Before I open a PR, I wanted to confirm the preferred approach:
A) <approach A — e.g., fix in this repo by modifying X>
B) <approach B — e.g., upstream fix in related-repo>

I can implement either direction. Happy to adjust based on your preference.

等待维护者回复后再开始编写代码。如果活跃项目在 24-48 小时后仍未收到回复，请采用最保守的方法继续（在当前仓库中进行范围最小的修复）。

2.2 制定 PR 策略

计划先以草稿 PR 的形式提交。只有满足以下条件后，才将其转换为可供审查的状态：

• CI 通过
• 维护者认可该方法（通过问题评论或 PR 审查）

阶段 3：仓库设置

3.1 Fork 并克隆

gh repo fork <owner>/<repo> --clone --remote
cd <repo>

3.2 确定开发分支

不要默认使用 main。检查近期已合并 PR 的目标分支：

gh pr list -R <owner>/<repo> --state merged --limit 10 \
  --json baseRefName,mergedAt

使用近期合并记录中最常见的 baseRefName。

3.3 阅读贡献指南

按以下顺序检查文件（阅读存在的文件）：

CONTRIBUTING.md
.github/CONTRIBUTING.md
.github/PULL_REQUEST_TEMPLATE.md
.github/PULL_REQUEST_TEMPLATE/

提取以下信息：

• 必需的提交信息格式
• 测试要求
• 预提交钩子或代码检查要求
• DCO／CLA 要求
• 分支命名规范

3.4 了解 CI

ls .github/workflows/

阅读 CI 配置，了解 PR 将运行哪些检查。找出以下检查对应的命令：

• 代码检查／格式化
• 类型检查
• 单元测试
• 集成测试
• 预提交钩子

3.5 设置环境

按照项目文档说明的流程进行设置。进行任何更改之前，先运行完整测试套件，确认基线测试通过。

阶段 4：代码修复

4.1 每个问题单独创建分支

git checkout -b fix/issue-<number>-<short-desc> <base-branch>

4.2 实现原则

• 如果问题评论中有维护者建议的方案，优先采用该方案
• 最小化修复：只更改修复问题所必需的内容。不要重构周边代码、添加功能，也不要顺便做“改进”
• 遵循项目风格：遵循现有的代码模式、命名规范和架构
• 不要硬编码：避免使用硬编码值，除非项目已在相同场景中使用这些值
• 添加测试：每项修复都需要对应的测试，且该测试本应能发现这个 Bug。遵循项目现有的测试模式

4.3 测试更改

运行项目的测试套件。所有现有测试都必须通过，新测试也必须通过。如果项目有类型检查或代码检查，也要运行。

特定语言的验证：

• Python：pytest、mypy、ruff（或项目使用的工具）
• TypeScript：npx tsc --noEmit、项目测试命令
• Rust：cargo check && cargo test
• Go：go build ./... && go test ./...

阶段 5：提交并提交 PR

5.1 提交前检查

如果项目使用提交前钩子：

pre-commit run --all-files

提交前修复所有问题。

5.2 提交规范

# Configure author
git config user.name "<user's name>"
git config user.email "<user's email>"

# Commit with DCO sign-off
git commit -s -m "<type>: <description>

Fixes #<issue-number>"

规则：

• 遵循项目的提交消息格式（查看近期提交作为示例）
• 添加 Fixes #<number> 或 Closes #<number>，以自动关联问题
• 不要添加 Generated by Claude、Co-Authored-By: claude 或任何 AI 署名
• 使用变基保持历史记录整洁，绝不强制推送

5.3 推送并创建 PR

git push -u origin fix/issue-<number>-<short-desc>

按照项目模板创建草稿 PR：

gh pr create --draft --title "<type>: <short description>" \
  --body "$(cat <<'EOF'
## Summary
<1-2 sentences describing the fix>

Fixes #<issue-number>

## Changes
- <bullet points of what changed>

## Test plan
- <how this was tested>
EOF
)"

5.4 处理 CI 结果

• CI 通过：在 PR 中评论说明已准备好进行审查，并将其转为非草稿
• CI 因你的代码而失败：修复问题并推送新的提交，不要 amend
• CI 因基础设施问题而失败（网络超时、测试不稳定、服务中断）：评论说明失败与你的更改无关，并请求重新运行

阶段 6：提交后

6.1 如果 PR 未合并便被关闭

不要慌。常见原因及应对方式：

原因	应对方式
修复已合并到上游	询问是否可以改为向上游仓库贡献
方案被拒绝	询问对方偏好的方案，并提出重新修改
重复提交	表示理解，并提出协助审查另一个 PR
范围过大	提出拆分为较小的 PR

已关闭 PR 的模板：

Thanks for the feedback. I understand the fix direction has shifted to <X>.
Would it be helpful if I submitted a PR to <upstream-repo> instead?
Happy to contribute wherever it's most useful.

6.2 如果有人要求更改

及时处理审查反馈。每次修改都作为新的提交（审查期间不要 squash，维护者可能希望看到修改过程）。只有维护者提出要求时才 squash。

应避免的反模式

以下是在实际贡献中出现过的失败情况：

1. 在错误的层级修复：你在仓库 A 中修复问题，但维护者在关闭你的 PR 前几分钟，已在仓库 B 中创建 PR。预防措施：阶段 1.4 检查上游 + 阶段 2 事先沟通。

2. PR 堆积：5 个人针对同一个问题提交 PR。预防措施：阶段 1.2 检查是否有竞争 PR + 阶段 2 认领工作。

3. 过度设计：在修复之外添加错误处理、类型注解、重构或“改进”。预防措施：阶段 4.2 的最小化修复原则。

4. 混淆 CI 基础设施问题：把 CI 中不稳定的测试或网络超时误认为代码问题。预防措施：阶段 5.4 明确排查 CI 失败原因。

5. 未沟通便提交：事先没有在问题中沟通就提交 PR。预防措施：阶段 2 的事先沟通是强制要求。

6. 基准分支错误：项目以 dev 分支进行开发，却将 PR 提交到 main。预防措施：阶段 3.2 检测分支。