| name | oss-contrib |
| description | Use when contributing to open source projects from forked repositories. Handles upstream sync, CONTRIBUTING.md compliance, code style matching, PR preparation, and project-specific patterns. Activates for fork management, PR template filling, and upstream workflow compliance. |
Open Source Contribution Workflow
Quick Reference
| Step | Action |
|---|
| 1. Sync | git fetch upstream && git merge upstream/main |
| 2. Research | Read CONTRIBUTING.md, PR templates, CLA requirements |
| 3. Branch | Create feature branch from synced default branch |
| 4. Code | Match upstream style exactly - no personal preferences |
| 5. Test | Run upstream's test suite, match their test patterns |
| 6. PR | Follow their PR template, fill all required fields |
Pre-Contribution Checklist
Before writing any code:
-
Sync fork with upstream
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
-
Read contribution guide
CONTRIBUTING.md in repo root.github/PULL_REQUEST_TEMPLATE.md- CLA/DCO signing requirements
- Required CI checks and labels
-
Create feature branch
git checkout -b fix/issue-description
-
Scope the change
- Only modify files directly related to the issue
- Never refactor or "improve" unrelated code
- Never add features beyond what was requested
Code Style Matching
The most important rule: match the upstream project's style exactly.
Before writing code, check:
- Indentation (spaces vs tabs, 2 vs 4)
- Quote style (single vs double)
- Import ordering and grouping
- Naming conventions (snake_case vs camelCase)
- Test patterns and fixtures
- Docstring format (Google, NumPy, Sphinx)
- Error handling patterns
- Linter/formatter config (
.editorconfig, pyproject.toml, .eslintrc)
Do NOT apply personal preferences. Do NOT run your own formatters unless they match upstream's config.
PR Best Practices
- Title: Match upstream convention (check recent merged PRs for format)
- Description: Fill every section of their PR template
- Commits: Squash to clean history if they prefer, keep atomic if they prefer
- Tests: Always include tests - match their test patterns exactly
- Scope: One logical change per PR
- CI: Ensure all required checks pass before requesting review
Adding Project-Specific Patterns
Create reference files in references/ for projects you regularly contribute to. Each file should document:
- Test fixture patterns and markers
- Import style and ordering rules
- PR template requirements
- Commit message format
- Any AI disclosure or CLA requirements
PR Template Compliance
Many open source projects require specific PR template fields. Always check:
AI Disclosure
Some projects (e.g., Apache Airflow) require an AI disclosure checkbox:
- [x] This PR was generated with the help of AI tools
Always fill this honestly if the project requires it.
CLA / DCO Requirements
| Type | How to Sign | Detection |
|---|
| CLA (Contributor License Agreement) | Web form, usually one-time per project | Look for CLA bot comment on PR |
| DCO (Developer Certificate of Origin) | git commit -s (adds Signed-off-by trailer) | Look for DCO check in CI |
Contributor Statements
Some projects (e.g., awslabs repos) require specific license text in contributions:
- Read CONTRIBUTING.md carefully for exact wording
- Include required license link text verbatim
- Don't paraphrase legal language
PR Quality Bar
Before submitting to any open source project:
- Is this a real problem? (Not cosmetic, not a style preference)
- Does the fix justify the review burden on maintainers?
- Is the PR scoped to exactly one logical change?
- Have you read recent merged PRs to understand their bar?
Common Pitfalls
| Mistake | Prevention |
|---|
| Forgetting to sync upstream before branching | Always git fetch upstream first |
| Applying personal code style | Run upstream's linter, check recent merged PRs |
| Modifying files outside fix scope | Review git diff before committing |
| Missing PR template fields | Read template file, fill every section |
| Not running full test suite locally | Run tests before pushing |
| Adding unnecessary refactoring | Keep changes minimal and focused |
| Ignoring CI failures | Fix all failures before requesting review |
| Skipping AI disclosure checkbox | Always fill honestly if required |
| Missing CLA/DCO signing | Check CONTRIBUTING.md for requirements |
| Bundling multiple fixes in one PR | One logical change per PR |
| Self-promotional PRs (awesome-list adds) | Focus on real problems the project has |
Fork Recovery
If fork relationship is broken (e.g., repo was made private then public):
- Clone the branch with your changes locally
- Delete the broken fork on GitHub
- Re-fork from upstream
- Push your branch to the fresh fork
- Create new PR
Stale PR Management
When PRs go unreviewed:
- Wait 1-2 weeks, then leave a polite ping comment
- If no response after 4 weeks, consider closing with a note
- Check if the maintainer is active on other PRs/issues
- Some projects have seasonal review cycles - check their activity patterns
