contributor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contributor

贡献者

Automated open source contribution workflow that takes you from a GitHub repo URL to merged PRs, with built-in safeguards against common contribution failures.

自动化开源贡献工作流，助你完成从GitHub仓库URL到PR合并的全流程，并内置针对常见贡献失败场景的防护机制。

Why this skill exists

此技能的存在意义

Open source contributions fail for predictable reasons: fixing in the wrong layer (your PR gets closed because the maintainer preferred an upstream fix), colliding with other contributors, not following project conventions, or over-engineering a simple fix. This workflow prevents each of those failures through systematic pre-checks.

开源贡献失败往往源于可预见的原因：在错误层级修复（你的PR被关闭，因为维护者更倾向于上游修复）、与其他贡献者工作冲突、未遵循项目规范，或是对简单修复过度设计。本工作流通过系统性预检查可避免上述各类失败。

Phase 1: Reconnaissance

第一阶段：调研

Before writing any code, gather intelligence about the project and its contribution landscape.

在编写任何代码前，先收集关于项目及其贡献环境的信息。

1.1 Identify the target

1.1 确定目标

Ask the user for:

The GitHub repo URL (e.g.,
```
pydantic/pydantic-ai
```
)
Their GitHub username and email for commits
Any specific issue they want to work on (or ask to scan for available ones)

向用户收集以下信息：

GitHub仓库URL（例如：
```
pydantic/pydantic-ai
```
）
用于提交的GitHub用户名和邮箱
想要处理的特定问题（或请求扫描可用问题）

1.2 Scan for available issues

1.2 扫描可用问题

Use

gh

CLI to find issues worth contributing to:

bash

undefined

使用

gh

CLI寻找适合贡献的问题：

bash

undefined

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

检查每个候选问题是否有竞争PR

gh pr list -R <owner>/<repo> --state open
--search "<issue_number> in:title,body"


**Filter criteria** (apply in order):
1. No assignee
2. No open PR already fixing it (check both linked PRs and title/body search)
3. Fewer than 5 competing PRs
4. Prefer labels: `bug`, `good first issue`, `help wanted`
5. Prefer issues with maintainer comments suggesting a fix direction

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 Deep-read issue comments

1.3 深度阅读问题评论

For each candidate issue, read the full comment thread:

bash

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

Extract:

Maintainer fix direction: Do they prefer fixing here or in an upstream dependency?
Suggested approach: Any code pointers, file references, or architectural guidance?
Blockers: Is this waiting on another PR or release?
Who's working on it: Even without assignment, someone might have commented "I'll take this"

针对每个候选问题，完整阅读评论线程：

bash

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

提取以下信息：

维护者的修复方向：他们倾向于在此仓库修复还是在上游依赖中修复？
建议方案：是否有代码指向、文件引用或架构指导？
阻塞因素：是否等待其他PR或版本发布？
正在处理的人员：即使没有分配负责人，也可能有人评论“我来处理这个”

1.4 Check for upstream redirection

1.4 检查上游重定向

This is the single most common failure mode. Before committing to any fix:

bash

undefined

这是最常见的失败模式。在确定任何修复方案前：

bash

undefined

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

检查相关仓库中提及此问题的近期PR

gh pr list -R <owner>/<related-repo> --state open --limit 10
--json title,body | grep -i "<issue_number>|<issue_keywords>"


If there's any signal the fix belongs elsewhere, stop and ask the user before proceeding.

gh pr list -R <owner>/<related-repo> --state open --limit 10
--json title,body | grep -i "<issue_number>|<issue_keywords>"


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

Phase 2: Pre-communication

第二阶段：预沟通

Never submit a PR cold. Always communicate your intent first.

切勿直接提交PR。务必先沟通你的意向。

2.1 Post a solution outline on the issue

2.1 在问题下发布解决方案大纲

Before writing code, leave a comment on the issue with your proposed approach. This serves two purposes: it claims the work (politely), and it gives maintainers a chance to redirect you before you waste effort.

Template:

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.

Wait for maintainer response before proceeding to code. If no response after 24-48 hours on an active project, proceed with the most conservative approach (smallest scope fix in the current repo).

编写代码前，在问题下留下评论说明你的方案。这有两个作用：礼貌地“认领”工作，以及让维护者有机会在你浪费精力前纠正方向。

模板：

您好，我一直在研究这个问题，已找到根本原因是<X>。

在提交PR前，我想确认首选方案：
A) <方案A — 例如：修改X在此仓库修复>
B) <方案B — 例如：在相关仓库进行上游修复>

我可以实现任意一种方案。愿意根据您的偏好调整。

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

2.2 Draft PR strategy

2.2 草稿PR策略

Plan to open as a Draft PR first. Convert to ready-for-review only after:

CI passes
Maintainer acknowledges the approach (via issue comment or PR review)

计划先创建草稿PR。仅在以下情况后转为“待审核”状态：

CI通过
维护者认可方案（通过问题评论或PR审核）

Phase 3: Repository Setup

第三阶段：仓库设置

3.1 Fork and clone

3.1 复刻并克隆

bash

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

bash

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

3.2 Determine the development branch

3.2 确定开发分支

Don't assume

main

. Check what recent merged PRs target:

bash

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

Use the most common

baseRefName

from recent merges.

不要默认使用

main

分支。查看近期合并的PR目标分支：

bash

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

使用近期合并PR中最常用的

baseRefName

。

3.3 Read contribution guidelines

3.3 阅读贡献指南

Check these files in order (read whichever exist):

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

Extract:

Required commit message format
Test requirements
Pre-commit hooks or linting requirements
DCO/CLA requirements
Branch naming conventions

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

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

提取以下信息：

要求的提交消息格式
测试要求
预提交钩子或代码检查要求
DCO/CLA要求
分支命名规范

3.4 Understand CI

3.4 了解CI机制

bash

ls .github/workflows/

Read the CI config to know what checks will run on your PR. Identify the commands for:

Linting / formatting
Type checking
Unit tests
Integration tests
Pre-commit hooks

bash

ls .github/workflows/

阅读CI配置，了解PR将运行哪些检查。确定以下操作的命令：

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

3.5 Set up the environment

3.5 设置环境

Follow the project's documented setup process. Run the full test suite once to establish a passing baseline before making any changes.

遵循项目文档的设置流程。在进行任何修改前，先运行完整测试套件以确保基线正常。

Phase 4: Code Fix

第四阶段：代码修复

4.1 Branch per issue

4.1 按问题创建分支

bash

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

bash

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

4.2 Implementation principles

4.2 实现原则

Adopt the maintainer's suggested approach if one exists in the issue comments
Minimal fix: change only what's necessary to fix the issue. Don't refactor surrounding code, add features, or "improve" things along the way
Match project style: follow the existing code patterns, naming conventions, and architecture
No hardcoding: avoid hardcoded values unless the project already uses them in the same context
Add tests: every fix needs a corresponding test that would have caught the bug. Follow the project's existing test patterns

遵循维护者建议的方案：如果问题评论中有明确方案
最小化修复：仅修改修复问题所需的内容。不要重构周边代码、添加功能或顺便“优化”其他内容
匹配项目风格：遵循现有代码模式、命名规范和架构
避免硬编码：除非项目在相同场景下已使用硬编码值，否则不要使用
添加测试：每个修复都需要对应的测试，以确保能发现该bug。遵循项目现有测试模式

4.3 Test your changes

4.3 测试修改

Run the project's test suite. All existing tests must pass. Your new test must also pass. If the project has type checking or linting, run those too.

Language-specific verification:

Python:
```
pytest
```
,
```
mypy
```
,
```
ruff
```
(or whatever the project uses)
TypeScript:
```
npx tsc --noEmit
```
, project test command
Rust:
```
cargo check && cargo test
```
Go:
```
go build ./... && go test ./...
```

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

语言特定验证：

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

Phase 5: Commit and Submit

第五阶段：提交并推送

5.1 Pre-commit checks

5.1 预提交检查

If the project uses pre-commit hooks:

bash

pre-commit run --all-files

Fix any issues before committing.

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

bash

pre-commit run --all-files

提交前修复所有问题。

5.2 Commit conventions

5.2 提交规范

bash

undefined

bash

undefined

Configure author

配置作者

git config user.name "<user's name>" git config user.email "<user's email>"

Commit with DCO sign-off

带DCO签署的提交

git commit -s -m "<type>: <description>

Fixes #<issue-number>"


Rules:
- Follow the project's commit message format (check recent commits for examples)
- Include `Fixes #<number>` or `Closes #<number>` to auto-link
- No `Generated by Claude`, `Co-Authored-By: claude`, or any AI attribution
- Use rebase to keep history clean, never force push

git commit -s -m "<type>: <description>

Fixes #<issue-number>"


规则：
- 遵循项目的提交消息格式（查看近期提交示例）
- 包含`Fixes #<number>`或`Closes #<number>`以自动关联问题
- 不要添加`Generated by Claude`、`Co-Authored-By: claude`或任何AI署名
- 使用rebase保持历史整洁，切勿强制推送

5.3 Push and create PR

5.3 推送并创建PR

bash

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

Create a Draft PR following the project's template:

bash

gh pr create --draft --title "<type>: <short description>" \
  --body "$(cat <<'EOF'

bash

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

遵循项目模板创建草稿PR：

bash

gh pr create --draft --title "<type>: <short description>" \
  --body "$(cat <<'EOF'

Summary

摘要

<1-2 sentences describing the fix>

Fixes #<issue-number>

<1-2句话描述修复内容>

Fixes #<issue-number>

Changes

修改内容

<bullet points of what changed>

<修改点的项目符号列表>

Test plan

测试计划

<how this was tested>

EOF )"

undefined

<测试方式> EOF )"

undefined

5.4 Handle CI results

5.4 处理CI结果

CI passes: Comment on PR that it's ready for review, convert from draft
CI fails due to your code: Fix it, push new commit, don't amend
CI fails due to infrastructure (network timeouts, flaky tests, service outages): Comment explaining the failure is unrelated to your changes and request a rerun

CI通过：在PR下评论表示待审核，将其从草稿转为正式状态
CI因你的代码失败：修复问题，推送新提交，不要修改历史提交
CI因基础设施失败（网络超时、不稳定测试、服务中断）：评论说明失败与你的修改无关，请求重新运行

Phase 6: After Submission

第六阶段：提交后处理

6.1 If PR is closed without merge

6.1 如果PR未被合并即关闭

Don't panic. Common reasons and responses:

Reason	Response
Fix moved upstream	Ask to contribute to the upstream repo instead
Approach rejected	Ask what approach they'd prefer, offer to redo
Duplicate	Acknowledge, offer to help review the other PR
Scope too large	Offer to split into smaller PRs

Template for closed PRs:

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.

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

原因	应对
修复移至上游	请求改为向上游仓库贡献
方案被拒绝	询问他们偏好的方案，提议重新实现
重复提交	表示理解，提议帮助审核其他PR
范围过大	提议拆分为更小的PR

关闭PR的回复模板：

感谢反馈。我理解修复方向已转向<X>。
我改为向<upstream-repo>提交PR是否有帮助？
愿意在最需要的地方贡献力量。

6.2 If changes are requested

6.2 如果需要修改

Address review feedback promptly. Make each revision a new commit (don't squash during review — the maintainer may want to see the evolution). Only squash if the maintainer asks.

及时处理审核反馈。每次修订都创建新提交（审核期间不要合并提交——维护者可能希望看到修改过程）。仅在维护者要求时再合并提交。

Anti-patterns to avoid

需避免的反模式

These are real failure modes from production contributions:

Fixing in the wrong layer: You fix in repo A, but the maintainer creates a PR in repo B minutes before closing yours. Prevention: Phase 1.4 upstream check + Phase 2 pre-communication.
PR pile-up: 5 people submit PRs for the same issue. Prevention: Phase 1.2 competing PR check + Phase 2 claiming the work.
Over-engineering: Adding error handling, type annotations, refactoring, or "improvements" beyond the fix. Prevention: Phase 4.2 minimal fix principle.
CI infrastructure confusion: A flaky test or network timeout in CI gets mistaken for a code problem. Prevention: Phase 5.4 explicit CI failure triage.
Silent submission: Submitting a PR without any prior communication on the issue. Prevention: Phase 2 pre-communication is mandatory.
Wrong base branch: PRing against
```
main
```
when the project develops on
```
dev
```
. Prevention: Phase 3.2 branch detection.

这些是实际贡献中真实存在的失败模式：

错误层级修复：你在仓库A修复，但维护者在关闭你的PR前几分钟在仓库B提交了PR。预防措施：第一阶段1.4的上游检查 + 第二阶段的预沟通。
PR堆积：5人针对同一问题提交PR。预防措施：第一阶段1.2的竞争PR检查 + 第二阶段的工作认领。
过度设计：在修复之外添加错误处理、类型注解、重构或“优化”内容。预防措施：第四阶段4.2的最小化修复原则。
CI基础设施混淆：将不稳定测试或网络超时导致的CI失败误认为代码问题。预防措施：第五阶段5.4的明确CI失败分类。
静默提交：未在问题下进行任何沟通就直接提交PR。预防措施：第二阶段的预沟通是强制性要求。
错误基准分支：向
```
main
```
分支提交PR，但项目实际在
```
dev
```
分支开发。预防措施：第三阶段3.2的分支检测。