open-source-contribution

Open-Source Contribution Workflow

Complete workflow for contributing high-quality PRs to open-source projects.

User Preference: Comprehensive Contributions

When user says "langsung gas dan maksimalkan" or "contribusi maksimal" or "bantu dia jadi terbaik":

• Build COMPREHENSIVE features, not minimal PRs
• Multiple related features in one PR is OK if cohesive
• Production-ready quality (tests, docs, error handling)
• Think like a 10-year veteran engineer
• Maximize impact: Analyze competitors, identify missing features, build world-class solutions
• Multi-phase approach: Quick wins first (1-2 hours), then game changers (4-5 hours)
• Quality over speed: Fix TypeScript errors immediately, don't push broken code

Pre-Contribution Analysis

1. Analyze the Project

Before forking, understand what's missing:

# Clone to analyze
git clone https://github.com/owner/repo.git
cd repo

# Check structure
ls -la
find src -name "*.tsx" | head -20

# Check existing features
grep -r "TODO\|FIXME" src/

# Check open issues/PRs
gh issue list --repo owner/repo
gh pr list --repo owner/repo

Compare with competitors:

• What do similar tools have that this doesn't?
• What are the ESSENTIAL missing features?
• What would make this project world-class?

Prioritize by impact:

• 🔥 CRITICAL: Features without which the tool is unusable (file tree, terminal, editor)
• 🎯 HIGH: Features that significantly improve UX (keyboard shortcuts, search)
• ✨ NICE: Polish and quality-of-life improvements (loading states, empty states)

2. Fork and Clone

# Fork via GitHub CLI
gh repo fork owner/repo --remote

# Or manually fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/repo.git
cd repo
git remote add upstream https://github.com/owner/repo.git

2. Star the Original Repo

Always star before contributing:

# Check if already starred
gh repo view owner/repo --json viewerHasStarred

# Star the repo
gh api --method PUT /user/starred/owner/repo

3. Check Open PRs (Avoid Duplicates)

gh pr list --repo owner/repo --json number,title,author

Development Workflow

1. Create Feature Branch

git checkout main
git pull upstream main
git checkout -b feat/your-feature-name

2. Make Changes

Use file tools (write_file, patch) to implement features.

3. CRITICAL: Quality Checks BEFORE Committing

TypeScript/JavaScript

# Type check (fast, low memory)
npx tsc --noEmit

# Common errors to fix:
# - TS6133: Unused variable/import/parameter
# - TS2304: Cannot find name
# - TS2345: Type mismatch

Fix unused variables:

// ❌ Bad
const { data, error } = useQuery();  // error unused
return <div>{data}</div>;

// ✅ Good
const { data } = useQuery();
return <div>{data}</div>;

Fix unused imports:

// ❌ Bad
import { useState, useEffect } from 'react';  // useEffect unused

// ✅ Good
import { useState } from 'react';

Fix unused parameters:

// ❌ Bad
items.map((item, idx) => <div key={item.id}>{item.name}</div>);  // idx unused

// ✅ Good
items.map((item) => <div key={item.id}>{item.name}</div>);

Python

mypy src/
ruff check .

Rust

cargo clippy -- -D warnings
cargo fmt --check

4. Commit with Conventional Commits

git add .
git commit -m "feat(scope): add feature

- Detailed change 1
- Detailed change 2
- Detailed change 3

Closes #issue_number"

Commit types:

• feat: — New feature
• fix: — Bug fix
• refactor: — Code restructure
• docs: — Documentation
• test: — Tests
• chore: — Maintenance

5. Push and Create PR

git push -u origin feat/your-feature-name

gh pr create --repo owner/repo \
  --title "feat: Add Feature Name" \
  --body "## Overview
  
Comprehensive description of changes.

## Features
- Feature 1
- Feature 2

## Testing
- Test approach

See docs/FEATURE.md for details."

6. Fix TypeScript Errors in PR

If CI fails with TypeScript errors:

# Check errors
npx tsc --noEmit

# Fix errors (use patch/write_file)

# Commit fix
git add .
git commit -m "fix: remove unused variables (TypeScript errors)"
git push

Quality Standards

Code Quality

• ✅ No TypeScript errors (npx tsc --noEmit passes)
• ✅ No unused variables/imports/parameters
• ✅ Proper error handling
• ✅ Type-safe (no any, no @ts-ignore)

Documentation

• ✅ README updated if needed
• ✅ Add docs/ files for complex features
• ✅ Code comments for non-obvious logic
• ✅ Examples in documentation

Testing

• ✅ Unit tests for new features
• ✅ Integration tests if applicable
• ✅ Manual testing documented

PR Description

• ✅ Clear overview
• ✅ List of changes
• ✅ Testing approach
• ✅ Screenshots/demos if UI changes

Multi-Feature Contributions

When building comprehensive features (user says "gas semua" or "maksimalkan"):

Strategy: Phased Approach

Phase 1: Quick Wins (1-2 hours each)

• Essential features that are fast to implement
• High impact, low complexity
• Example: Keyboard shortcuts, loading states

Phase 2: Core Features (2-4 hours each)

• Essential features that require more work
• Game-changing functionality
• Example: File tree, terminal integration

Phase 3: Advanced Features (4-6 hours each)

• Complex features that complete the experience
• Example: Code editor (Monaco), Git integration

PR Organization

1. Group related features in one PR if cohesive
2. Example: Command Palette + Keyboard Shortcuts (related)
3. Not: Command Palette + Git Integration (separate concerns)

1. Create multiple PRs for independent features
2. PR #1: Command Palette + Keyboard Shortcuts
3. PR #2: Loading States + Empty States
4. PR #3: File Tree Sidebar
5. PR #4: Terminal Integration
6. PR #5: Code Editor (Monaco)

1. Each PR should be:
2. Self-contained (works independently)
3. Reviewable (not too large, <1000 lines ideal)
4. Production-ready (complete, tested, documented)
5. Quality-checked: TypeScript passes, no unused variables

Workflow for Multiple PRs

# PR #1
git checkout main
git checkout -b feat/command-palette
# Implement, test, commit
npx tsc --noEmit  # CRITICAL: Check before push
git push -u origin feat/command-palette
gh pr create --repo owner/repo --title "..." --body "..."

# PR #2 (don't wait for #1 review)
git checkout main
git checkout -b feat/loading-states
# Implement, test, commit
npx tsc --noEmit  # CRITICAL: Check before push
git push -u origin feat/loading-states
gh pr create --repo owner/repo --title "..." --body "..."

# Continue for all features

Benefits:

• Maintainer can review/merge independently
• Faster iteration (parallel review)
• Easier to revert if needed
• Clear git history

Common Pitfalls

❌ Don't:

• Submit PR with TypeScript errors
• Leave unused variables/imports
• Skip documentation
• Make PRs too large (>1000 lines)
• Mix unrelated features

✅ Do:

• Run npx tsc --noEmit before every commit
• Clean up unused code
• Add comprehensive docs
• Split large features into multiple PRs
• Keep each PR focused

Example: Full Contribution

# 1. Fork and star
gh repo fork owner/repo --remote
gh api --method PUT /user/starred/owner/repo

# 2. Check existing PRs
gh pr list --repo owner/repo

# 3. Create branch
git checkout -b feat/command-palette

# 4. Implement feature (use file tools)

# 5. Quality check
npx tsc --noEmit
# Fix any errors

# 6. Commit
git add .
git commit -m "feat(ui): add command palette with keyboard shortcuts"

# 7. Push
git push -u origin feat/command-palette

# 8. Create PR
gh pr create --repo owner/repo \
  --title "feat(ui): Add Command Palette and Keyboard Shortcuts" \
  --body "Comprehensive command palette with 8 global shortcuts..."

# 9. Fix CI errors if any
npx tsc --noEmit
# Fix, commit, push

# 10. Repeat for next feature
git checkout main
git pu