贡献者
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
当所有这些都成立时使用此技能:您正在为您不维护的存储库做出贡献(维护者可以关闭您的 PR 而无需解释)。这项工作涉及以下一项或多项:源代码、测试、文档、构建配置。您希望合并 PR,而不仅仅是提交。不要将此用于:您自己的存储库、具有共享上下文的内部团队 PR、维护人员正在等待您的热修复分支,或者琐碎的单行更改(一条注释就足够了)。
PR 关闭的最常见原因是贡献者认为可接受的内容与维护者已经写下的内容不匹配。在编写代码之前解决这个问题。
CONTRIBUTING.md 不是风格建议。将每个编号规则视为合并的前提条件。特别注意:人工智能辅助缴款条款。在人工智能公关浪潮之后,许多项目在 2024-2026 年添加了这些内容。典型的措辞:“未经事先讨论的人工智能生成的 PR 可能会被关闭”、“你必须能够解释每一行”、“一个问题,一个 PR”。如果存在此条款,则您需要对项目进行明确披露(请参阅第 4 阶段),并且您必须保持 PR 较小。
“小公关”是相对的。在打开 PR 之前,运行: 这会告诉您项目的实际合并 PR 大小分布。如果你的 PR 比最近最大的合并大 5-10 倍,那就是一个红色信号——在提交之前拆分。请参阅`references/phase1_discovery.md`了解基线标准和分割启发式。
范围合同是您在打开编辑器之前写给自己的一个段落:目标:<一句话>。范围:<项目符号列表,3-5 项>。明确超出范围:<项目符号列表 - 具体说明您在诱人时会拒绝添加的内容>。然后,每次进行编辑时,询问:“这在范围内吗?”如果您发现自己“当我在这里时……”,请停下来重新审视合同。范围蔓延是关闭而不合并的最大单一来源——有关范围规则部分,请参阅`references/phase2_implementation.md`。
始终从上游 `main` (或项目的默认分支)分支,永远不要从你的分支的 `main` 分支,这可能已经过时了。
抵制范围合同未直接要求的任何变更。特别是:不要“当我在这里”重构周围的代码。不要重新格式化您没有触及的行(您的格式化程序可能与项目的不同,即使两者都说“Prettier”)。为了清楚起见,不要重命名变量,除非重命名可以解决问题。如果后续改进确实有价值,请在合并后提交一个单独的问题或打开一个单独的 PR。
使用常规提交:`<type>(<scope>): <description>`,其中类型为`feat | fix | docs | refactor | test | chore | ci | perf`。每个提交都应该可以单独审查。当评论提示修复时,请在推送之前使用`git commit --fixup=<sha>`并用`git -c sequence.editor=: rebase -i --autosquash origin/main`挤压 - 有关完整的修复工作流程,请参阅`references/phase2_implementation.md`。
# GitHub Contributor
A phase-based playbook for shipping pull requests that maintainers actually want to merge. The skill is structured around the real PR lifecycle — discovery → implementation → quality gates → description → post-submission — because each phase has its own failure modes and the most common mistake is doing the right thing at the wrong phase (e.g., writing the perfect description for a PR that's 10× too large).
## Phase 0 — When to use this skill
Use this skill when **all** of these are true:
- You are contributing to a repo you do **not** maintain (the maintainer can close your PR without explanation).
- The work touches one or more of: source code, tests, docs, build config.
- You want the PR merged, not just submitted.
Do **not** use this for: your own repos, internal team PRs with shared context, hot-fix branches where a maintainer is waiting on you, or trivial single-line changes (one comment is enough).
## Phase 1 — Pre-PR Discovery
The most common reason PRs get closed is a mismatch between what the contributor assumes is acceptable and what the maintainer has already written down. Solve this before writing code.
### Step 1.1 — Read CONTRIBUTING.md as a hard contract
CONTRIBUTING.md is **not** style advice. Treat every numbered rule as a precondition for merge. Pay special attention to:
- **AI-assisted contribution clauses.** Many projects added these in 2024-2026 after the AI PR wave. Typical phrasing: "AI-generated PRs without prior discussion may be closed", "you must be able to explain every line", "one issue, one PR". If this clause exists, you owe the project explicit disclosure (see Phase 4) and you must keep the PR small.
- **Issue-first rules.** Some projects require a feature-request issue to exist before any feature PR is opened.
- **Per-language test commands.** If CONTRIBUTING.md says `pnpm test:unit && cargo test`, those are the commands you run, not whatever your IDE prefers.
If CONTRIBUTING.md is missing, that itself is a red flag — see [`references/project_evaluation.md`](references/project_evaluation.md).
### Step 1.2 — Sanity-check your PR size against the project's baseline
A "small PR" is relative. Before opening a PR, run:
```bash
gh pr list --repo <owner>/<repo> --state merged --limit 10 \
--json number,title,author,additions,deletions \
--jq '.[] | "#\(.number) +\(.additions)/-\(.deletions): \(.title)"'
```
This tells you the project's actual merged-PR size distribution. If your PR is **5–10× larger than the biggest recent merge**, that is a red signal — split before submitting. See [`references/phase1_discovery.md`](references/phase1_discovery.md) for the baseline rubric and split heuristics.
### Step 1.3 — Write a one-paragraph scope contract before coding
A scope contract is a single paragraph you write **to yourself** before opening your editor:
> Goal: <one sentence>. In scope: <bullet list, 3–5 items>. Explicitly out of scope: <bullet list — be specific about what you will resist adding when it's tempting>.
Then, every time you make an edit, ask: "Is this in scope?" If you find yourself "while I'm in here…"-ing, stop and revisit the contract. Scope creep is the single biggest source of close-without-merge — see [`references/phase2_implementation.md`](references/phase2_implementation.md) for the scope-discipline section.
## Phase 2 — Implementation
### Step 2.1 — Branch off `main` immediately after fetching upstream
```bash
git fetch origin
git switch -c feat/short-descriptive-name origin/main
```
Always branch from upstream `main` (or the project's default branch), never from your fork's `main`, which may be stale.
### Step 2.2 — Make the smallest diff that solves the problem
Resist any change that is not directly required by your scope contract. In particular:
- Do **not** "while I'm here" refactor surrounding code.
- Do **not** reformat lines you didn't touch (your formatter may differ from the project's, even if both say "Prettier").
- Do **not** rename variables for clarity unless the renaming is the fix.
If a follow-up improvement is genuinely valuable, file a separate issue or open a separate PR after this one is merged.
### Step 2.3 — Conventional Commits, one logical change per commit
Use [Conventional Commits](https://www.conventionalcommits.org/): `<type>(<scope>): <description>` where type is `feat | fix | docs | refactor | test | chore | ci | perf`. Each commit should be reviewable on its own.
When a review prompts a fix, use `git commit --fixup=<sha>` and squash with `git -c sequence.editor=: rebase -i --autosquash origin/main` before pushing — see [`references/phase2_implementation.md`](references/phase2_implementation.md) for the full fixup workflow.
## Phase 3 — Quality Gates
Maintainers' trust is built by evidence, not by claims. The point of this phase is to produce evidence you can paste into the PR.
### Step 3.1 — Run the project's full lint + test suite locally
Read the exact commands from CONTRIBUTING.md. Typical examples (use what your project specifies):
```bash
pnpm typecheck && pnpm format:check && pnpm test:unit
cargo fmt --check && cargo clippy --all-targets && cargo test
```
If any check fails, fix it before continuing. Do not push a PR with red local checks expecting CI to clarify — that wastes maintainer time.
### Step 3.2 — For GUI / desktop apps: run real end-to-end with isolation
For Tauri/Electron/Cocoa apps you almost certainly cannot use `pnpm dev` directly without contaminating your real installation. The pattern is **isolate the data directory first, then run the real binary**:
1. Find the project's test-isolation hook (often `XXX_TEST_HOME`, `XXX_DATA_DIR`, or a config flag in `config.rs` / `paths.go`).
2. Point it at `/tmp/<app-name>-e2e/` before launching.
3. Trigger the feature through whatever real surface the user would (URL scheme, CLI arg, deeplink).
4. Verify by reading the actual persisted state (SQLite, JSON files), not just by visual inspection.
5. Capture screenshots of the GUI for the PR description.
The full isolation recipe, including how to trigger deeplinks via Tauri's single-instance forward without touching macOS LaunchServices, is in [`references/phase3_quality_gates_and_e2e.md`](references/phase3_quality_gates_and_e2e.md).
### Step 3.3 — Self-audit: did you actually do what you're about to claim?
Before writing the PR description, list every "I tested…" / "I verified…" / "I ran…" statement you intend to make. For each one, ask: "What's my evidence?" If the answer is "I think I did" or "it should work", you have not actually done it. Write only what you can defend.
This rule prevents the most damaging trust failure: a maintainer running your "tested" command and finding it doesn't work.
### Step 3.4 — Push-time verification
Local tests passing is not the finish line. Before you call the PR merge-ready, run the push-time checklist:
1. **Visibility check** — confirm the target repo is actually public/private as you assume:
```bash
gh repo view <owner>/<repo> --json visibility,isPrivate,defaultBranchRef
```
2. **Security hooks** — if pre-push fails, fix the rule or the content; do not `--no-verify`.
3. **Push succeeds** — if it fails with 503/auth errors, check `git config --global --get-regexp url` for stale URL rewrites.
4. **Mergeability check** — `git push` succeeding does not mean GitHub can merge:
```bash
gh pr view <pr-number> --repo <owner>/<repo> --json mergeable,mergeStateStatus
```
Full details (URL rewrites, PII-hook false positives, `--force-with-lease` caveats) are in [`references/push_time_gotchas.md`](references/push_time_gotchas.md).
## Phase 4 — PR Description Writing
A great PR description does three jobs: (1) lets the maintainer decide in 30 seconds whether to merge, (2) gives reviewers everything they need to verify without DM'ing you, (3) creates a written record that survives team turnover.
### Step 4.1 — Structure
Use this skeleton. Detailed templates and a test-coverage-matrix example are in [`references/phase4_pr_description.md`](references/phase4_pr_description.md) and [`references/communication_templates.md`](references/communication_templates.md).
```
## Summary / 概述
<two sentences — what changed and why it matters>
## What / 变更内容
<bulleted list of commits with their purpose, or files with their purpose>
## Why / 动机
<the problem this solves; if no prior issue, briefly justify why>
## Test Plan / 测试计划
<exact commands a maintainer can run; coverage matrix for non-trivial changes>
## Backward Compatibility / 向后兼容
<state explicitly; don't make the maintainer infer>
## Security Considerations
<only if the change touches auth, inputs, or shared state>
## Screenshots / 截图
<for UI changes — see Step 4.3>
## Related Issue
<Fixes #N, or explain why no issue exists>
## Checklist
<the project's PR template checklist, with real evidence of each>
## AI-Assisted Disclosure
<see Step 4.4>
```
### Step 4.2 — Test coverage matrix (for non-trivial changes)
When you've added more than 2 tests, present them as a table mapping each test to the behavior it locks in. This makes review much faster than reading test code:
```markdown
| Layer | Test | What it proves |
|---|---|---|
| URL parsing | `test_parse_provider_with_extra_env` | extraEnv query param extracted |
| Security | `test_extra_env_stringifies_scalars_and_skips_invalid_values` | bool/number stringified; null/array/object dropped |
```
### Step 4.3 — Screenshots without polluting the repo
`gh` CLI does **not** support image attachments to PRs (the underlying upload API at `uploads.github.com` is browser-only and rejects PAT tokens). Three workable approaches:
1. **Preferred — let the user drag images in the GitHub web UI.** Leave clearly marked placeholders in your PR body draft (e.g. `[SCREENSHOT_1_PLACEHOLDER]`). When the user edits the PR on github.com, they drag images into the markdown, GitHub uploads them to `user-images.githubusercontent.com`, and the placeholders are replaced. Zero pollution.
2. **Fallback — orphan branch on your fork.** Create an orphan branch (e.g. named `assets-pr-N-screenshots`), commit images, reference them via `raw.githubusercontent.com`. Pollutes your fork but not the PR diff.
3. **Last resort — third-party image host.** Persistence + privacy are unclear; avoid for anything sensitive.
### Step 4.4 — AI-Assisted Disclosure (when CONTRIBUTING.md or maintainer norms call for it)
If the project's CONTRIBUTING.md mentions AI-assisted PRs, or the maintainer has commented skeptically about AI output on past PRs, add a short disclosure at the bottom of the PR body. Be specific about what you did, not vague reassurances.
```markdown
## AI-Assisted Disclosure
Per CONTRIBUTING.md §N:
1. I have read every line; happy to walk through any function or design choice.
2. Tested locally: <list actual commands you ran with their results>.
3. Single-topic PR scoped to <one sentence>.
4. <opened/will open> Issue #N for discussion.
5. AI tools used: Claude Code for drafting; <list any others>. Final review and decisions are mine.
```
The disclosure is not magic — it doesn't excuse a bad PR. But missing it on a project that asks for it is an instant trust hit.
## Phase 5 — Post-Submission
### Step 5.1 — Respond to automated bot reviews explicitly
Modern projects use Codex, Claude bot, CodeRabbit, etc. for first-pass review. Their comments appear as **review comments on specific lines**, not as PR-level comments. Reply to each finding directly (so maintainers see the resolution next to the finding), citing the commit hash and the function/test that resolves it:
```bash
gh api repos/<owner>/<repo>/pulls/<pr>/comments \
-X POST \
-F in_reply_to=<finding_comment_id> \
-f body="Addressed in commit \`<sha>\`: <function or test name>. <one-sentence explanation>. Thanks for the catch!"
```
`<finding_comment_id>` is the numeric ID from the comment's URL (`#discussion_rXXXXXXXX`). Full bot-reply workflow in [`references/phase5_post_submission.md`](references/phase5_post_submission.md).
### Step 5.2 — Rebase against upstream main without losing review history
When upstream `main` advances and your PR conflicts:
```bash
git fetch origin
git rebase origin/main
# resolve conflicts file by file
git add <files>
git -c sequence.editor=: rebase --continue
git push fork <branch> --force-with-lease
```
Use `--force-with-lease`, never plain `--force`. The `lease` variant aborts if someone else (or a bot) pushed to your branch in between, which prevents you from silently destroying review threads.
If you applied a small post-review cleanup (a `--fixup` commit), squash it into the relevant commit with autosquash so the merged history stays clean. See [`references/phase2_implementation.md`](references/phase2_implementation.md) for the full sequence.
### Step 5.3 — When sub-agent / counter-review surfaces "findings", filter before responding
If you run a counter-review agent (or a maintainer's bot floods you with 20+ findings), don't paste them all into the PR. For each finding ask three questions:
| Filter | Discard if |
|---|---|
| Probability | "Could this actually happen in this codebase?" → No |
| Cost | "Would fixing it cost more than the risk?" → Yes |
| Scenario | "Is this scenario already prevented upstream?" → Yes |
The point of counter-review is to surface things you didn't think of, not to mandate fixing every theoretical concern. Filter ruthlessly, then explain in the PR why you accepted vs. declined each suggestion.
## Reference Files
| File | Use for |
|---|---|
| [`references/phase1_discovery.md`](references/phase1_discovery.md) | CONTRIBUTING.md parsing, PR size baseline rubric, scope-contract templates |
| [`references/phase2_implementation.md`](references/phase2_implementation.md) | Fixup commit + autosquash workflow, scope-discipline anti-patterns |
| [`references/phase3_quality_gates_and_e2e.md`](references/phase3_quality_gates_and_e2e.md) | Isolated-home pattern, single-instance forward, SQLite verification, screencapture + window focus |
| [`references/phase4_pr_description.md`](references/phase4_pr_description.md) | Body skeleton, test-coverage-matrix, AI disclosure templates, screenshot placeholder pattern |
| [`references/phase5_post_submission.md`](references/phase5_post_submission.md) | `gh api in_reply_to` recipe, `--force-with-lease` semantics, counter-review filtering |
| [`references/push_time_gotchas.md`](references/push_time_gotchas.md) | Git remote URL rewrites, PII-hook false positives, mergeability verification, force-push caveats |
| [`references/case_study_cc-switch_pr_2634.md`](references/case_study_cc-switch_pr_2634.md) | Full real-world walkthrough including dev log, SQLite dump, screenshots |
| [`references/case_study_cc-switch_pr_1624.md`](references/case_study_cc-switch_pr_1624.md) | Frontend/state-management rebase case study — async init guards, test coupling, i18n conflicts |
| [`references/pr_checklist.md`](references/pr_checklist.md) | Original consolidated checklist (legacy; phase docs supersede the workflow sections) |
| [`references/project_evaluation.md`](references/project_evaluation.md) | Project health rubric for the discovery step |
| [`references/communication_templates.md`](references/communication_templates.md) | Issue-claim, review-response, and after-merge templates |
| [`references/high_quality_pr_case_study.md`](references/high_quality_pr_case_study.md) | OpenClaw PR #39763 walkthrough — small-fix case study |
## Anti-Patterns to Avoid
These are the failure modes that close PRs even when the underlying code is fine. Each one comes from a real PR.
1. **Fabricated test claims.** Writing "tested locally with `pnpm dev`" when you actually only ran the unit tests. A maintainer will try it and lose trust permanently.
2. **PR 5–10× the project's recent merge baseline.** Even good code at this size signals "AI dump" to many maintainers.
3. **Rebase-time scope creep.** Bringing an unrelated upstream feature into your branch "while resolving conflicts" turns a fix PR into a feature PR with no warning.
4. **Mixing refactors into a fix commit.** Reviewers can't tell which line caused the bug fix; either split or use a `--fixup` commit on the refactor.
5. **Force-pushing without `--lease`** mid-review. Destroys review threads silently.
6. **Ignoring bot review comments.** Even when the bot is wrong, reply explaining why — silence reads as "didn't notice".
7. **Burying the disclosure.** AI-assisted disclosure goes in the PR body, not as a footnote in a commit message no one reads.
8. **Reading CONTRIBUTING.md after writing the PR.** Half of CONTRIBUTING.md rules are about how the PR is structured, not what the code does.
9. **Submitting features without an issue when the project requires one.** Even if the issue is created retroactively the same hour, the timestamp matters to maintainers.
10. **Pasting raw counter-review output.** 20 findings in a PR body looks like noise. Filter, then respond.
## Quick Reference
### Required gh CLI commands
```bash
gh repo view <owner>/<repo> --json visibility,isPrivate,defaultBranchRef
gh pr list --repo <owner>/<repo> --state merged --limit 10
gh pr view <pr-number> --repo <owner>/<repo> --json title,body,commits,mergeable,reviewDecision
gh pr edit <pr-number> --repo <owner>/<repo> --body-file pr_body.md
gh api repos/<owner>/<repo>/pulls/<pr>/comments -X POST -F in_reply_to=<id> -f body="..."
```
### Conventional Commits cheat sheet
```
feat(<scope>): user-visible new behavior
fix(<scope>): user-visible bug fix
refactor(<scope>): no behavior change
docs(<scope>): documentation only
test(<scope>): tests only
chore(<scope>): tooling / build / housekeeping
perf(<scope>): measurable performance change
ci(<scope>): CI config only
```
### Key metrics for a high-quality PR
Based on successful contributions to active projects:
- Files changed: 1-5 for fixes, up to ~15 for features with tests
- Production code diff: under 200 lines if possible; rest is tests / docs
- PR description: 200-600 lines including evidence; matrix tables welcome
- First-response time to bot/maintainer: under 24h
- CI passing on first push: target
If your PR misses two or more of these by a lot, re-read Phase 1 before submitting.
按说明文件中的顺序排列。
阶段 0——何时使用该技能
第一阶段——公关前发现
步骤 1.1 — 将 CONTRIBUTING.md 视为硬合约
步骤 1.2 — 根据项目基线对 PR 大小进行健全性检查
步骤 1.3 — 在编码之前编写一段范围合同
文件/命令 -> pnpm test:unit && cargo test · references/project_evaluation.md · references/phase1_discovery.md · references/phase2_implementation.md · main · <type>(<scope>): <description> · feat | fix | docs | refactor | test | chore | ci | perf · git commit --fixup=<sha>
内容校验值 -> 51d3adb32078
当前原文的自动摘译,尚未人工审校。
步骤 1.3 — 在编码之前编写一段范围合同
范围合同是您在打开编辑器之前写给自己的一个段落:目标:<一句话>。范围:<项目符号列表,3-5 项>。明确超出范围:<项目符号列表 - 具体说明您在诱人时会拒绝添加的内容>。然后,每次进行编辑时,询问:“这在范围内吗?”如果您发现自己“当我在这里时……”,请停下来重新审视合同。范围蔓延是“不合并而关闭”的最大单一来源——有关范围规则部分,请参阅
references/phase2_implementation.md。