/open-source-contribution

name: open-source-contribution
description: Comprehensive workflow for contributing to open-source projects with quality checks
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [GitHub, Open-Source, Quality, TypeScript, Contribution]
    related_skills: [github-pr-workflow, github-code-review]
origin: original
source_repo: kevinnft/ai-agent-skills
source_url: https://github.com/kevinnft/ai-agent-skills
source_license: MIT
language: en

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