sagargupta16/oss-contrib

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:

1. Sync fork with upstream

   git fetch upstream
   git checkout main
   git merge upstream/main
   git push origin main
   

2. Read contribution guide

   • CONTRIBUTING.md in repo root
   • .github/PULL_REQUEST_TEMPLATE.md
   • CLA/DCO signing requirements
   • Required CI checks and labels

3. Create feature branch

   git checkout -b fix/issue-description
   

4. 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

1. Title: Match upstream convention (check recent merged PRs for format)
2. Description: Fill every section of their PR template
3. Commits: Squash to clean history if they prefer, keep atomic if they prefer
4. Tests: Always include tests - match their test patterns exactly
5. Scope: One logical change per PR
6. 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):

1. Clone the branch with your changes locally
2. Delete the broken fork on GitHub
3. Re-fork from upstream
4. Push your branch to the fresh fork
5. 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