OSS Contribution Best Practices

分类: 数据库与数据存储 | 上传者: costajohnt | 下载: 0 | 版本: v1.0（最新）
当用户致力于开源贡献、响应维护者反馈、编写 PR 描述、处理问题、跟进休眠 PR 或需要有关开源礼仪和最佳实践的指导时，应使用此技能。
更新日志: Source: GitHub https://github.com/costajohnt/oss-autopilot
目录结构

当前层级: tree/main/skills/oss-contribution/
📄 SKILL.md 12.0 KB
SKILL.md

---
name: OSS Contribution Best Practices
description: This skill should be used when the user is working on open source contributions, responding to maintainer feedback, writing PR descriptions, working on issues, following up on dormant PRs, or needs guidance on open source etiquette and best practices.
version: 1.1.0
---

# Open Source Contribution Best Practices

**Reference:** Based on [opensource.guide](https://opensource.guide/how-to-contribute/)

## Core Principles

**Be a good open source citizen:**
1. Respect maintainers' time - they're often unpaid volunteers
2. Read contribution guidelines before contributing
3. Communicate clearly and professionally
4. Be patient - open source moves at its own pace
5. Give back to the community when you can

## Minimal Diff Discipline

Every line in a PR diff must be directly related to the issue being fixed. Unrelated formatting changes (whitespace, quote style, trailing commas, import reordering, line breaks) make diffs noisy, harder to review, and signal carelessness. Maintainers will flag or reject PRs with formatting bloat.

**Rules:**
1. **Only touch lines the fix requires.** Don't reorder imports, change quote styles, fix whitespace, or add trailing commas in existing code — unless those changes are part of the fix itself.
2. **Scope formatter output.** If the repo's formatter must be run (e.g., CI requires it), review the formatter's changes afterward. Use `git diff` to identify formatting-only changes. Use `git checkout -- {files}` only for files where ALL changes are formatting-only. For files with mixed changes, use targeted edits to surgically remove formatting hunks. (In interactive terminal contexts, `git add -p` can also be used for hunk-level staging.)
3. **Match the repo's style, don't impose your own.** If the repo uses single quotes, use single quotes in your new code. If it uses tabs, use tabs. Never convert existing style to a different one.

**When formatting IS the fix:** If the issue itself is about formatting (e.g., "run prettier on codebase", "fix inconsistent indentation"), then formatting changes are in scope. In all other cases, they are not.

## Responding to Code Review Feedback

### Mindset

Maintainer feedback is a gift - they're investing time to help you improve. Even critical feedback should be received gracefully.

### Response Approach

- Address every point they raise
- Keep it short. One or two sentences is usually enough.
- Push updates promptly after discussion
- Mark conversations as resolved after addressing
- If you feel resistance to a request, investigate deeper — the maintainer likely knows something you don't. If you still think there's an issue after investigating, raise it to the human contributor — never override the maintainer

### Assumptions and Verification

When a maintainer requests changes, these rules govern how you respond:

1. **Maintainer is right by default.** If a maintainer says "do X," your starting assumption is that X is correct and appropriate for their codebase. Do not second-guess their judgment about their own project.

2. **Verify, never assume.** Before running any tool (linter, formatter, type checker), check the project's CI configuration to confirm that tool is actually enforced. Read `.pre-commit-config.yaml`, `.github/workflows/`, `Makefile`, or equivalent before deciding what to run. A tool that exists in `devDependencies` but is not in CI is not authoritative.

3. **Try before estimating scope.** When asked to make a change, attempt the simplest implementation first. Do not respond with effort estimates, propose TODOs, or suggest deferring to a follow-up PR. If the change turns out to be genuinely complex after attempting it, report what you found to the human.

4. **Pushback = escalate, don't override.** If you believe a maintainer's request is incorrect or harmful, raise the concern to the human contributor. Never push back on a maintainer directly, never ignore the request, and never silently do something different from what was asked.

5. **No TODOs as substitutes.** A maintainer asking for a change expects the change in this PR. Responding with a TODO comment or "I'll handle this in a follow-up" is not an acceptable response unless the maintainer explicitly suggested that approach.

### Pre-Push Review Checkpoint

Before pushing commits that address review feedback:

1. Run the project's code review tooling on your diff (the pr-review-toolkit agents if installed, otherwise the built-in pre-commit-reviewer)
2. Fix any issues found (bugs, style violations, missing error handling)
3. Re-run until clean — no actionable findings
4. Only then push your changes

This prevents maintainers from seeing issues that could have been caught locally. It's especially important when responding to feedback — pushing sloppy fix-up commits undermines credibility.

### PR Readiness Gate (Mandatory)

A PR is NEVER "ready" until all of these pass:

1. **Local lint/type check**: Run the repo's linters and type checkers
2. **Test suite**: Run the full test suite locally
3. **Code review**: Run review agents (pr-review-toolkit or pre-commit-reviewer)
4. **Fix and re-run**: Fix all findings, re-run checks
5. **Convergence**: Repeat until zero Critical/Recommended findings
6. **Push and verify CI**: Push and confirm CI passes remotely
7. **Only then** declare the PR ready for maintainer review

The tool should NEVER say "PR is ready", "work is complete", or "changes are done" without having run through this complete loop. This applies to:
- New contributions (draft-first workflow)
- Responses to maintainer feedback
- CI fix pushes
- Any commit that will be seen by maintainers

### Things to Avoid

- Being defensive or dismissive
- Long justifications for every decision
- Ignoring feedback points
- Taking days to respond
- Assuming what tools the project's CI enforces without checking CI config files
- Substituting TODOs or "follow-up PR" proposals for changes the maintainer requested in this PR
- Running tools not enforced by CI and treating their output as authoritative

## Writing Good PR Descriptions

### Structure

```markdown
## Summary
[1-2 sentences explaining what this PR does]

## Problem
[What problem does this solve? Link to issue if applicable]

## Solution
[Brief explanation of your approach]

## Testing
[How you tested the changes]

## Screenshots (if UI changes)
[Before/after screenshots]
```

### Tips

- Link to related issues: "Fixes #123" or "Closes #123"
- Keep it concise - maintainers review many PRs
- Highlight anything unusual or that needs special attention
- Don't pad with unnecessary sections

## Working on Issues

### Before Starting

1. Read the entire issue and all comments
2. Check if someone else is already working on it (check for linked PRs)
3. Make sure you understand the requirements
4. Verify you have the skills/time to complete it

### Work-First Approach

Do NOT comment to "claim" the issue before you have working code. The workflow is:

1. Fork/clone the repo
2. Implement the fix
3. Verify tests pass locally
4. Open a PR that references the issue (e.g., "Fixes #123")

The PR itself is the claim. A separate "I'm working on this" comment is unnecessary noise when the PR is coming soon.

### When to Comment on the Issue

Only comment on the issue itself when:
- You need clarification from the maintainer before starting
- The approach is ambiguous and you want confirmation
- The issue is old and you want to confirm it's still relevant

### If You Can't Solve It

Move on silently. Don't comment that you tried and failed. Don't mark the issue in any way. Remove it from your list and continue to the next one.

### After Opening a PR

- Reference the issue in the PR body: "Fixes #123" or "Closes #123"
- Only comment on the issue if the PR needs additional context

## Following Up on Dormant PRs

- **7 days:** Light check-in ("Anything else needed from my side?")
- **14 days:** Direct follow-up ("Still on your radar? Happy to make changes.")
- **30 days:** Final check ("Understand if priorities shifted. Let me know!")

Be patient, not pushy. Only follow up once per timeframe. Check if maintainers are active elsewhere before escalating.

## Time Management

### Sustainable Pace

- Don't over-commit
- It's okay to work on one PR at a time
- Quality over quantity
- Contribute consistently, not in bursts

### Managing Multiple PRs

- Prioritize PRs that are close to merge
- Respond to feedback within 24-48 hours
- Don't let PRs go stale
- Know when to close and move on

## PR Quality Checklist

Before submitting any PR, verify:

### Required
- [ ] **Issue Reference**: PR links to issue (`Closes #X` or `Fixes #X`)
- [ ] **Description Quality**: Explains what changed and why
- [ ] **Title Quality**: Descriptive, properly formatted (e.g., `fix: resolve login timeout`)
- [ ] **Focused Changes**: One logical change per PR (< 10 files, < 400 lines ideal)
- [ ] **Minimal Diff**: No unrelated formatting changes (whitespace, quotes, imports, trailing commas)

### Conditional
- [ ] **Tests Included**: If project requires tests, add them
- [ ] **Docs Updated**: If behavior changed, update docs

### Optional
- [ ] **Branch Naming**: Follows convention (`feature/`, `fix/`, `docs/`)
- [ ] **Screenshots**: Included for UI changes

**Tip:** Use the `pr-compliance-checker` agent to validate your PR before requesting review.

## Communication Etiquette

### Always
- Be patient - maintainers are often volunteers
- Respond promptly to feedback (within 24-48 hours)
- Keep discussions public and constructive
- Accept decisions gracefully, even if you disagree

### Never
- Argue or be defensive
- Ping maintainers repeatedly
- Take rejection personally
- Ignore feedback points
- Make demands or set ultimatums

### Writing Style (Avoiding AI Tells)

AI-generated comments have recognizable patterns. Avoid these:

- **No changelogs in comments.** "Changes in the latest commit:" with bullet points is a dead giveaway. Describe what you did in a sentence, or let the diff speak.
- **Vary your openings.** Don't start every response with "Thanks for the review!" or "Good catch!" Sometimes just jump to the substance.
- **Match their length.** If the maintainer wrote two sentences, don't respond with four paragraphs.
- **Read the whole thread first.** Asking about something explained three comments up is the fastest way to lose credibility.
- **Mean what you say.** Don't defend a position then immediately abandon it. Push back or agree -- pick one.
- **Figure things out yourself.** If a maintainer says "add a screenshot," look at existing examples. Don't ask them to explain the tooling.

### When to Respond Personally

Some situations require the human contributor, not an AI tool:

- **Maintainer frustration or AI accusations** — respond honestly and personally
- **Visual/subjective tasks** — screenshots, design opinions, UX judgments
- **Heated discussions** — any thread about AI ethics, contribution policies, or governance
- **Process questions with obvious answers** — look at existing examples instead of asking

## Contribution Ethics

### Do

- Attribute work properly (co-authors for human pair work)
- Give credit to human contributors in PR descriptions
- Share knowledge with other contributors

### Don't

- Add AI attribution to commits or PRs:
  - No `Co-Authored-By: Claude` trailers
  - No "Generated with Claude Code" in PR descriptions
  - No robot emoji attributions
  - No mentions of AI assistance in comments
- Claim credit for others' work
- Submit low-quality PRs just for contribution graphs
- Spam repos with trivial changes

## Failure Protocol

When a task or approach fails, **STOP and report back to the user** with what failed and why. Do not silently switch strategies or improvise workarounds — let the user decide how to proceed. Documented fallbacks (e.g., gh CLI fallback) are permitted if the user is informed first. Undocumented or improvised fallbacks are never permitted.

## Resources

- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Best Practices for Maintainers](https://opensource.guide/best-practices/)
- [Building Welcoming Communities](https://opensource.guide/building-community/)
登录后下载/点赞/收藏 ❤ 8 | ★ 0
OSS Contribution Best Practices

目录结构

SKILL.md

举报内容

提示
