zhongwei/gh-devkade-collaborator-skills-oss-contribution-framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:19:43 +08:00
commit 2359544dbc
22 changed files with 7017 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,13 @@
{
"name": "oss-contribution-framework",
"description": "Systematic 6-phase framework for contributing to open source projects from issue discovery to PR creation",
"version": "1.0.0",
"author": {
"name": "devkade",
"email": "zhongweili@tubi.tv"
},
"skills": [
"./skills",
"./"
]
}

1
.claude/commands/oss-contribution-framework.md Normal file
View File

@@ -0,0 +1 @@
Use the oss-contribution-framework skill to guide through the complete OSS contribution workflow from issue discovery to PR creation.

1
.claude/commands/oss:codebase-exploration.md Normal file
View File

@@ -0,0 +1 @@
Use the oss:codebase-exploration skill to systematically understand project structure, conventions, and architecture.

1
.claude/commands/oss:documentation-pr.md Normal file
View File

@@ -0,0 +1 @@
Use the oss:documentation-pr skill to document changes and create a comprehensive pull request.

1
.claude/commands/oss:issue-analysis.md Normal file
View File

@@ -0,0 +1 @@
Use the oss:issue-analysis skill to perform deep analysis of issue requirements, scope, and expected outcomes.

1
.claude/commands/oss:issue-code-mapping.md Normal file
View File

@@ -0,0 +1 @@
Use the oss:issue-code-mapping skill to connect issue requirements to specific code locations and modification points.

1
.claude/commands/oss:issue-discovery.md Normal file
View File

@@ -0,0 +1 @@
Use the oss:issue-discovery skill to find and evaluate suitable issues for OSS contribution.

1
.claude/commands/oss:solution-implementation.md Normal file
View File

@@ -0,0 +1 @@
Use the oss:solution-implementation skill to design and implement the solution following project standards and best practices.

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# oss-contribution-framework
Systematic 6-phase framework for contributing to open source projects from issue discovery to PR creation

269
SKILL.md Normal file
View File

@@ -0,0 +1,269 @@
---
name: oss-contribution-framework
description: Systematic framework for contributing to open source projects. Guides through issue discovery, integrated analysis with code exploration, implementation, and PR creation. Use when starting OSS contributions, analyzing issues, or creating pull requests. Includes modular sub-skills for each contribution phase.
---
# OSS Contribution Framework
A comprehensive, step-by-step framework for making meaningful open source contributions. This skill orchestrates the entire contribution workflow from finding the right issue to submitting a polished pull request.
## Overview
This framework breaks down OSS contributions into four systematic phases, each with its own dedicated sub-skill. You can use the complete workflow or invoke individual phases as needed.
## Quick Start
**Full workflow:**
```
사용자: "이 프로젝트에 기여하고 싶어" or "OSS 기여 시작"
→ Framework guides through all 4 phases
```
**Individual phase:**
```
사용자: "이슈 분석해줘" or "코드 구현"
→ Activates specific sub-skill
```
## Four-Phase Workflow
### Phase 1: Issue Discovery & Triage
**Sub-skill:** `skills/issue-discovery.md`
Find and evaluate suitable issues to work on.
**Capabilities:**
- Filter issues by labels, difficulty, project activity
- Assess issue quality and clarity
- Evaluate if issue matches your skills
- Check for duplicate work or stale issues
**Triggers:**
- "좋은 이슈 찾아줘"
- "beginner-friendly 이슈 추천"
- "이 이슈가 적합한지 평가해줘"
### Phase 2: Issue Analysis & Code Exploration
**Sub-skill:** `skills/issue-analysis.md`
**INTEGRATED PHASE** - Deep analysis combining requirements extraction with codebase exploration and code-level mapping.
**Capabilities:**
- Extract core requirements and acceptance criteria
- Explore project structure and conventions
- Locate exact files and functions to modify
- Identify problem code and fix points
- Trace execution paths
- Map dependencies and impact
- Plan specific code modifications
**Triggers:**
- "이 이슈 분석해줘"
- "코드에서 어디를 고쳐야 하나?"
- "이슈와 코드 연결"
- "문제 있는 코드 찾기"
### Phase 3: Solution Implementation
**Sub-skill:** `skills/solution-implementation.md`
Design and implement the solution following project standards.
**Capabilities:**
- Design solution approach
- Write code following project conventions
- Add/update tests
- Handle edge cases
**Triggers:**
- "솔루션 구현"
- "이슈 해결 시작"
- "테스트 작성"
### Phase 4: Documentation & PR
**Sub-skill:** `skills/documentation-pr.md`
Document changes and create a comprehensive pull request.
**Capabilities:**
- Write clear PR description
- Document code changes
- Create changelog entries
- Prepare for review
**Triggers:**
- "PR 작성"
- "문서화"
- "pull request 준비"
## Workflow Orchestration
The main framework manages state and progress across phases:
### Initial Setup
When user starts contribution workflow:
1. **Detect starting point:**
- New contribution: Start at Phase 1
- Have issue URL: Start at Phase 2
- Already analyzed: Start at Phase 3
- Ready to implement: Start at Phase 5
2. **Gather context:**
- Repository URL or local path
- Issue number/URL (if available)
- User's familiarity with project
- Language/framework preferences
3. **Initialize tracker:**
```markdown
## 🎯 Contribution Progress
- [ ] Phase 1: Issue Discovery
- [ ] Phase 2: Issue Analysis & Code Exploration
- [ ] Phase 3: Solution Implementation
- [ ] Phase 4: Documentation & PR
**Current Phase:** [PHASE]
**Repository:** [REPO]
**Issue:** [ISSUE_URL]
```
### Phase Transitions
After completing each phase, checkpoint with user:
```
"Phase [N] 완료했습니다.
[SUMMARY OF FINDINGS]
다음 단계:
1. Phase [N+1] 진행 - [DESCRIPTION]
2. 현재 단계 심화 분석
3. 특정 부분 재검토
어떻게 진행할까요?"
```
### Progressive Context
Maintain and carry forward context between phases:
- **Phase 1 → 2:** Issue URL, labels, initial assessment, CONTRIBUTING.md requirements
- **Phase 2 → 3:** Requirements, project structure, exact code locations, modification plan
- **Phase 3 → 4:** Implementation changes, tests added, commits made
## Sub-Skill Invocation
Each sub-skill can be invoked independently or as part of the workflow.
**Independent usage:**
```
사용자: "이 이슈 분석해줘: https://github.com/..."
→ Directly loads Phase 2 sub-skill
```
**Within workflow:**
```
Framework: "Phase 2를 시작합니다..."
→ Internally loads skills/issue-analysis.md
→ Applies guidance and returns results
→ Updates progress tracker
```
## Adaptive Guidance
The framework adapts based on:
**Project type:**
- **Web app:** Focus on UI/UX, API, state management
- **CLI tool:** Focus on commands, flags, I/O
- **Library:** Focus on API design, backwards compatibility
- **Documentation:** Focus on clarity, examples, accuracy
**Issue type:**
- **Bug:** Root cause analysis, reproduction steps
- **Feature:** Design considerations, API surface
- **Refactor:** Code quality, test coverage maintenance
- **Docs:** Accuracy, completeness, examples
**User experience level:**
- **First contribution:** More guidance, explanations
- **Experienced:** Streamlined, focus on project-specific aspects
## Best Practices
**For optimal results:**
1. **Start early** - Engage framework before coding
2. **Be thorough** - Don't skip phases, especially exploration
3. **Communicate** - Comment on issue before starting work
4. **Test locally** - Verify changes before PR
5. **Follow conventions** - Match project style strictly
6. **Ask questions** - Engage maintainers when unclear
**Quality checklist:**
Before moving to Phase 4 (PR), verify:
- [ ] All requirements addressed
- [ ] Tests pass locally
- [ ] Code follows project conventions
- [ ] No unintended changes
- [ ] Documentation updated
- [ ] Commit messages are clear
## Advanced Features
### Multi-Issue Analysis
Compare and prioritize multiple issues:
```
"이 3개 이슈 중 어떤 걸 먼저 해야 할까?"
→ Analyzes difficulty, impact, learning value
```
### Contribution Strategy
Get personalized contribution roadmap:
```
"이 프로젝트에 장기적으로 기여하고 싶어"
→ Suggests progression path from simple to complex issues
```
### Review Preparation
Prepare for code review:
```
"PR 리뷰 대비"
→ Anticipates reviewer questions and concerns
```
## Reference Materials
Each phase has detailed references:
- `references/issue-patterns.md` - Common issue types and approaches
- `references/codebase-checklist.md` - Systematic exploration guide
- `references/pr-templates.md` - Template library for various projects
- `references/contribution-tips.md` - Project-specific guidelines
## Templates
Standard output templates in `assets/templates/`:
- `issue-analysis-template.md` - Structured issue breakdown
- `codebase-notes-template.md` - Project understanding notes
- `pr-checklist-template.md` - Pre-submission checklist
## Notes
- This framework is language and project-agnostic
- Adapt guidance to specific project conventions
- Always prioritize maintainer preferences
- Focus on sustainable, long-term contributions
- Build understanding, not just code changes
## Progressive Disclosure
1. **Start here** - SKILL.md for overview and workflow
2. **Load sub-skills** - Individual phase guidance as needed
3. **Consult references** - Detailed patterns and checklists
4. **Use templates** - Structured output formats

404
assets/templates/codebase-notes-template.md Normal file
View File

@@ -0,0 +1,404 @@
# Codebase Exploration Notes: [Project Name]
**Repository:** [URL or path]
**Explored:** [date]
**For Issue:** #[number]
**Language:** [primary language]
---
## Quick Reference
**Essential Commands:**
```bash
# Install dependencies
[command]
# Run dev server
[command]
# Run tests
[command]
# Lint/format
[command]
```
**Key Directories:**
- Source: `[path]`
- Tests: `[path]`
- Docs: `[path]`
---
## Project Summary
[2-3 sentences about what this project does and how it's structured]
**Purpose:** [What problem does this solve?]
**Target Users:** [Developer tool / Web app / Library / CLI / etc]
**Core Technologies:**
- Language: [language + version]
- Framework: [if applicable]
- Build tool: [tool]
- Testing: [framework]
**Project Maturity:**
- Age: [years or months]
- Activity: [active / moderate / slow]
- Contributors: [approximate count]
- Stability: [alpha / beta / stable / mature]
---
## Directory Structure
```
project-root/
├── [main-source-dir]/ - [purpose]
├── [test-dir]/ - [purpose]
├── [docs-dir]/ - [purpose]
├── [config-files] - [purpose]
└── [other-key-dirs]/ - [purpose]
```
**Organization Principle:**
- [ ] By feature (users/, products/, orders/)
- [ ] By layer (models/, views/, controllers/)
- [ ] By type (components/, utils/, services/)
- [ ] Hybrid approach
**Notes:**
[Any special organization patterns or unusual directory purposes]
---
## Code Conventions
### Naming Conventions
**Files:**
- Pattern: [kebab-case / PascalCase / snake_case]
- Extensions: [.js, .ts, .tsx, etc]
- Tests: [*.test.js / *_test.go / test_*.py]
**Code Elements:**
- Classes: [PascalCase]
- Functions: [camelCase / snake_case]
- Variables: [camelCase / snake_case]
- Constants: [UPPER_SNAKE_CASE / kConstant]
- Private: [_private / #private / __private]
**Examples from codebase:**
```[language]
// Actual examples from the project
class ExampleClass { }
function exampleFunction() { }
const EXAMPLE_CONSTANT = 'value'
```
### Code Style
**Formatting:**
- Indentation: [2 spaces / 4 spaces / tabs]
- Line length: [80 / 100 / 120 chars]
- Quotes: [single / double]
- Semicolons: [required / optional]
**Imports:**
```[language]
// Import order example from project
import external from 'package'
import internal from '@/internal'
import relative from './relative'
```
**Comments:**
- Documentation: [JSDoc / docstrings / rustdoc / etc]
- Inline: [when and how used]
- TODO format: [TODO: / TODO(name): / FIXME:]
**Error Handling:**
- Pattern: [try/catch / Result<T,E> / error codes]
- Custom errors: [how defined]
- Error messages: [format and style]
### Architectural Patterns
**Overall Pattern:**
[MVC / MVVM / Layered / Component-based / etc]
**State Management:**
[How application state is managed]
**Data Flow:**
[How data moves through the system]
**Dependency Direction:**
[e.g., UI → Services → Data Layer]
**Key Abstractions:**
- [Abstraction 1]: [purpose and how used]
- [Abstraction 2]: [purpose and how used]
---
## Testing
### Test Framework & Location
**Framework:** [Jest / pytest / JUnit / etc]
**Test Locations:**
- Unit tests: [path pattern]
- Integration tests: [path pattern]
- E2E tests: [path pattern]
**Test Naming:**
- Pattern: [describe/it / test_ / Test* / #[test]]
- Convention: [naming style for test descriptions]
### Test Structure
**Typical test pattern:**
```[language]
// Example test structure from the project
describe('FeatureName', () => {
it('should do X when Y', () => {
// Arrange
// Act
// Assert
})
})
```
**Common patterns:**
- Setup/teardown: [how handled]
- Fixtures: [location and usage]
- Mocks: [how created]
- Assertions: [library and style]
### Running Tests
```bash
# All tests
[command]
# Specific file
[command]
# With coverage
[command]
# Watch mode
[command]
```
**Coverage:**
- Target: [percentage if specified]
- Tool: [coverage tool used]
- Reports: [where generated]
---
## Development Workflow
### Setup
```bash
# Initial setup
git clone [repo]
cd [project]
[install command]
[setup environment]
```
**Prerequisites:**
- [Tool/version requirement 1]
- [Tool/version requirement 2]
### Development Commands
```bash
# Development mode
[command]
# Build
[command]
# Lint
[command]
# Format
[command]
# Type check (if applicable)
[command]
```
### Git Workflow
**Branch naming:** [pattern: feature/*, fix/*, etc]
**Commit format:**
```
type(scope): description
[longer explanation if needed]
```
**Pre-commit hooks:**
- [What runs automatically]
---
## CI/CD
**CI System:** [GitHub Actions / Travis / CircleCI / etc]
**Configuration:** [.github/workflows/* / .travis.yml / etc]
**CI Checks:**
- [ ] Tests
- [ ] Linting
- [ ] Type checking
- [ ] Build
- [ ] Coverage
- [ ] [Other checks]
**Important:** [Any CI-specific considerations]
---
## Reference Examples
### For My Work
**Similar features/patterns:**
1. **[Feature/Pattern 1]**
- File: `[path/to/file]:[line]`
- What it does: [description]
- Why relevant: [how it relates to my issue]
- Pattern to follow: [specific pattern]
2. **[Feature/Pattern 2]**
- File: `[path/to/file]:[line]`
- What it does: [description]
- Why relevant: [how it relates]
- Pattern to follow: [specific pattern]
3. **[Feature/Pattern 3]**
- File: `[path/to/file]:[line]`
- What it does: [description]
- Why relevant: [how it relates]
### Patterns to Replicate
- **[Pattern 1]:** [e.g., how errors are handled]
- Example: [file:line]
- Apply to: [my use case]
- **[Pattern 2]:** [e.g., how validation is done]
- Example: [file:line]
- Apply to: [my use case]
- **[Pattern 3]:** [e.g., how tests are structured]
- Example: [file:line]
- Apply to: [my use case]
### Patterns to Avoid
- **[Anti-pattern 1]:** [old code being refactored]
- **[Anti-pattern 2]:** [special case, don't generalize]
---
## Impact Analysis
### Files I'll Likely Modify
1. **`[path/to/file1]`**
- Reason: [why this file]
- Change type: [add / modify / delete]
- Confidence: [high / medium / low]
2. **`[path/to/file2]`**
- Reason: [why this file]
- Change type: [add / modify / delete]
- Confidence: [high / medium / low]
### Dependencies to Consider
**Upstream (what calls my changes):**
- [Dependency 1]: [description]
- [Dependency 2]: [description]
**Downstream (what my changes call):**
- [Dependency 1]: [description]
- [Dependency 2]: [description]
**Side effects:**
- [ ] File I/O
- [ ] Network calls
- [ ] Database operations
- [ ] State mutations
- [ ] Event emissions
### Risk Level
**Overall risk:** 🟢 Low / 🟡 Medium / 🔴 High
**Risk factors:**
- [Factor 1: e.g., modifying critical path]
- [Factor 2: e.g., poorly tested area]
**Mitigation:**
- [Strategy 1: e.g., add extra tests]
- [Strategy 2: e.g., incremental changes]
---
## Notes & Questions
### Key Observations
- [Observation 1: interesting pattern or consideration]
- [Observation 2: something to remember]
- [Observation 3: potential challenge]
### Still Unclear
- [ ] [Question 1: what still needs investigation]
- [ ] [Question 2: clarification needed]
- [ ] [Question 3: uncertainty]
### Resources
- Documentation: [links to relevant docs]
- Similar issues: [links to related issues/PRs]
- References: [external resources]
---
## Next Steps
✅ Exploration complete - Ready for **Phase 4: Issue-Code Mapping**
**Recommended focus:**
1. [Specific file/component to examine more closely]
2. [Pattern to understand deeper]
3. [Test to review as reference]
**Action items:**
- [ ] [Specific exploration task if needed]
- [ ] [Question to ask maintainer if needed]
- [ ] [Code to trace if needed]
---
## Personal Notes
[Any additional thoughts, reminders, or insights for myself]

226
assets/templates/issue-analysis-template.md Normal file
View File

@@ -0,0 +1,226 @@
# Issue Analysis: [Issue Title]
**Issue:** #[number] | **Type:** [bug/feature/refactor/docs/performance]
**URL:** [GitHub issue link]
**Status:** Ready to implement / Needs clarification
**Date:** [Analysis date]
---
## Summary
[2-3 sentence summary of what needs to be done and why]
---
## Requirements
### Core Requirements
[Based on issue type, fill in relevant section below]
#### For Bug Fixes
**Current Behavior:**
[What actually happens - be specific]
**Expected Behavior:**
[What should happen - reference docs/specs if available]
**Reproduction Steps:**
1. [Step 1]
2. [Step 2]
3. [Observe: ...]
**Environment:**
- Version: [version]
- Platform: [OS/browser/etc]
- Configuration: [relevant settings]
**Root Cause (Hypothesis):**
[Your initial theory of what's causing this]
**Affected Users:**
[Who hits this? How often? Severity: Critical/High/Medium/Low]
#### For Features
**User Story:**
As a [user type], I want [capability] so that [benefit].
**Functional Requirements:**
1. [Requirement 1 - must have]
2. [Requirement 2 - must have]
3. [Requirement 3 - nice to have]
**User Interface:**
- **Input:** [What user provides]
- **Output:** [What user sees/gets]
- **Interaction flow:** [Step-by-step user journey]
**Non-Functional Requirements:**
- Performance: [any constraints]
- Compatibility: [versions, platforms]
- Accessibility: [considerations]
#### For Refactoring
**Current Problems:**
1. [Problem 1: e.g., duplicated code across X files]
2. [Problem 2: e.g., poor separation of concerns]
3. [Problem 3: e.g., difficult to test]
**Desired Outcome:**
[What the code should look like after refactoring]
**Constraints:**
- [ ] No behavior changes
- [ ] All existing tests must pass
- [ ] No API changes (if library)
- [ ] [Other constraints]
### Edge Cases & Implicit Requirements
**Boundary Conditions:**
- [ ] Empty input: [how to handle]
- [ ] Large data: [limits, pagination]
- [ ] Special characters: [escaping, validation]
- [ ] Null/undefined: [default behavior]
**Error Handling:**
- [ ] Network failure: [retry logic, user feedback]
- [ ] Invalid input: [validation, error messages]
- [ ] Permissions: [who can do what]
- [ ] Resource exhaustion: [limits, throttling]
**Integration Concerns:**
- **Depends on:** [list dependencies]
- **Affects:** [list affected components]
- **Breaking change:** Yes ⚠️ / No ✅
- **Backwards compatibility:** [considerations]
**Non-Functional:**
- **Performance:** [requirements or concerns]
- **Security:** [validations needed]
- **Accessibility:** [ARIA, keyboard nav, etc]
- **Mobile/Responsive:** [considerations]
---
## Scope Definition
### In Scope (Minimal)
1. [Must-have item 1]
2. [Must-have item 2]
3. [Must-have item 3]
### In Scope (If Time Permits)
1. [Nice-to-have item 1]
2. [Nice-to-have item 2]
### Out of Scope
1. [Item to defer - with reason]
2. [Item to defer - with reason]
### Dependencies
- **Blocked by:** [list blocking issues]
- **Blocks:** [list issues waiting on this]
### Estimated Complexity
🟢 Simple (< 4 hours)
🟡 Moderate (1-2 days)
🔴 Complex (3+ days)
**Complexity Factors:**
- [Factor 1: e.g., need to learn new API]
- [Factor 2: e.g., touching critical code path]
- [Factor 3: e.g., requires significant testing]
---
## Acceptance Criteria
### Functional
- [ ] [Action] results in [observable outcome]
- [ ] [Condition] produces [expected result]
- [ ] [Feature] works with [existing feature]
- [ ] [Edge case] handled appropriately
### Quality
- [ ] All new code has tests (coverage > X%)
- [ ] No new linting errors
- [ ] No new type errors
- [ ] Documentation updated
- [ ] Existing tests pass
### Edge Cases
- [ ] [Edge case 1] handled correctly
- [ ] [Edge case 2] shows appropriate error
- [ ] [Edge case 3] returns expected default
### Integration
- [ ] Works on [platform 1]
- [ ] Compatible with [version X]
- [ ] No breaking changes (or documented)
- [ ] Integrates with [related feature]
---
## Implementation Notes
### Affected Components
- [Component 1: description of involvement]
- [Component 2: description of involvement]
- [Component 3: description of involvement]
### Key Considerations
- [Consideration 1: important factor to keep in mind]
- [Consideration 2: architectural constraint]
- [Consideration 3: performance implication]
### Potential Challenges
- **[Challenge 1]:** [description]
- Mitigation: [how to address]
- **[Challenge 2]:** [description]
- Mitigation: [how to address]
### Similar Patterns in Codebase
- [Similar feature/pattern 1] @ [file:line]
- [Similar feature/pattern 2] @ [file:line]
---
## Open Questions
[Questions to ask maintainer before implementation]
1. **[Specific aspect]**
- Current understanding: [what you think]
- Question: [what's unclear]
- Options: [potential approaches A, B, C]
- Preference: [your recommendation and why]
2. **[Edge case handling]**
- Scenario: [describe edge case]
- Question: Should this [A] or [B]?
- Precedent: [similar handling elsewhere, if found]
---
## Next Steps
✅ Analysis complete - Ready for **Phase 3: Codebase Exploration**
**Before coding, explore:**
1. [Specific file/component to understand]
2. [Test patterns to learn]
3. [Similar features to reference]
**Or if clarification needed:**
❓ Post questions to issue thread and wait for maintainer response
---
## Notes
[Any additional context, insights, or considerations]

457
assets/templates/pr-checklist-template.md Normal file
View File

@@ -0,0 +1,457 @@
# PR Submission Checklist
**Issue:** #[number]
**PR Title:** [Type]: [Brief description]
**Branch:** [branch-name]
**Date:** [date]
---
## Pre-Submission Checklist
### Code Quality
- [ ] **All tests pass locally**
```bash
[test command]
# Output: [all passing]
```
- [ ] **Linting passes**
```bash
[lint command]
# Output: [no errors]
```
- [ ] **Build succeeds**
```bash
[build command]
# Output: [success]
```
- [ ] **Type checking passes** (if applicable)
```bash
[type check command]
# Output: [no errors]
```
- [ ] **No compiler warnings**
- Checked: Yes / No / N/A
### Functionality
- [ ] **All requirements implemented**
- Requirement 1: ✅
- Requirement 2: ✅
- Requirement 3: ✅
- [ ] **Edge cases handled**
- Empty input: ✅
- Null/undefined: ✅
- Large data: ✅
- Invalid input: ✅
- [Other edge cases]: ✅
- [ ] **Error handling complete**
- Error messages clear
- Graceful degradation
- No crashes
- [ ] **Manual testing done**
- Tested on: [environment]
- Test scenarios: [list]
- Results: [all passed]
### Testing
- [ ] **New tests added**
- Unit tests: [count] added
- Integration tests: [count] added
- Test coverage: [percentage]
- [ ] **Test quality**
- Tests are meaningful (not just for coverage)
- Tests follow project conventions
- Tests have clear names
- Tests are independent
- [ ] **Existing tests still pass**
- All passing: Yes
- Any skipped: No
- Any modified: [list with reason]
### Documentation
- [ ] **Code comments added**
- Complex logic explained
- Public APIs documented
- TODOs addressed or tracked
- [ ] **README updated** (if needed)
- New features documented
- Examples added
- Installation updated
- [ ] **CHANGELOG entry added**
```markdown
## [Unreleased]
### [Added/Fixed/Changed]
- [Description] (#[issue])
```
- [ ] **API docs updated** (if applicable)
- Parameters documented
- Return values documented
- Examples provided
### Git Hygiene
- [ ] **Branch is up to date with main**
```bash
git fetch origin
git rebase origin/main
# Conflicts resolved: Yes/No
```
- [ ] **Commits are clean**
- Logical commits: Yes
- Clear messages: Yes
- No merge commits: Yes (or rebased)
- [ ] **No sensitive data**
- No API keys
- No passwords
- No personal data
- No secrets in history
- [ ] **No unintended changes**
- No debug code
- No commented code
- No formatting-only changes (unless intended)
- No temp files
### Self-Review
- [ ] **Reviewed entire diff**
- Read through all changes
- Checked for issues
- Verified quality
- [ ] **Code is clear**
- Variable names are descriptive
- Functions have single responsibility
- Logic is straightforward
- Comments where needed
- [ ] **Follows conventions**
- Naming matches project style
- Formatting is consistent
- Patterns match existing code
- No new paradigms introduced
- [ ] **No obvious bugs**
- Logic is correct
- Edge cases handled
- No potential null errors
- No off-by-one errors
### Completeness
- [ ] **All acceptance criteria met**
- [Criterion 1]: ✅
- [Criterion 2]: ✅
- [Criterion 3]: ✅
- [ ] **Issue fully resolved**
- Nothing left to do
- No half-implemented features
- No TODOs left unaddressed
- [ ] **No scope creep**
- Only issue requirements addressed
- No unrelated changes
- Additional ideas tracked separately
---
## PR Description Draft
### Title
```
[Type]: [Clear, concise description (50-70 chars)]
```
### Description
```markdown
## Summary
[2-3 sentences: what, why, how]
## Changes Made
- [Change 1]
- [Change 2]
- [Change 3]
## Type of Change
- [x] [Selected type]
## Related Issue
Fixes #[issue-number]
## How to Test
1. [Step 1]
2. [Step 2]
3. [Verify result]
## Screenshots (if applicable)
[Add screenshots or remove section]
## Checklist
- [x] Code follows style guidelines
- [x] Self-reviewed
- [x] Commented hard-to-understand areas
- [x] Documentation updated
- [x] No new warnings
- [x] Tests added and passing
## Additional Notes
[Any context, tradeoffs, or future work]
```
---
## CI/CD Preparation
### Expected CI Checks
- [ ] **Tests** - Should pass
- [ ] **Linting** - Should pass
- [ ] **Type checking** - Should pass
- [ ] **Build** - Should succeed
- [ ] **Coverage** - Should meet threshold ([X]%)
- [ ] **[Other checks]** - [Expected result]
### If CI Fails
**Plan:**
1. Check logs immediately
2. Reproduce locally
3. Fix and push update
4. Don't wait for reviewer if CI failing
---
## Communication Plan
### Before Creating PR
- [ ] **Comment on issue**
"Submitted PR #[number] to address this issue"
- [ ] **Tag appropriately** (if permissions)
- Type label (bug, enhancement, etc)
- Status label (ready for review, etc)
### After Creating PR
- [ ] **Monitor CI**
- Checks all passing
- Fix any failures immediately
- [ ] **Request review** (if needed)
- Specific reviewer requested
- Or wait for maintainer assignment
- [ ] **Be responsive**
- Check for comments daily
- Respond within 24-48 hours
- Make requested changes promptly
---
## Review Readiness
### Making Reviewer's Job Easy
- [ ] **PR is focused**
- Single concern
- Reasonable size (< 500 lines if possible)
- Clear purpose
- [ ] **Context provided**
- Clear description
- Test instructions
- Screenshots if UI change
- [ ] **Quality is high**
- No obvious issues
- Well-tested
- Follows conventions
- [ ] **Ready for feedback**
- Open to suggestions
- Will respond promptly
- Willing to iterate
### Potential Review Comments
**Prepare for:**
- Style/convention feedback → Will fix
- Architectural suggestions → Open to discuss
- Test coverage requests → Will add
- Documentation requests → Will improve
- Bug concerns → Will investigate
---
## Submission Commands
### Push Branch
```bash
# Ensure branch is up to date
git fetch origin
git rebase origin/main
# Push to remote
git push -u origin [branch-name]
# If rebased and need to force push
git push -f origin [branch-name]
```
### Create PR
**Via GitHub CLI:**
```bash
gh pr create \
--title "[Type]: [Description]" \
--body-file pr-description.md \
--label [label] \
--assignee @me
```
**Via Web:**
1. Go to repository on GitHub
2. Click "Pull requests"
3. Click "New pull request"
4. Select your branch
5. Fill in title and description
6. Create pull request
---
## Post-Submission
### Immediate Actions
- [ ] **Verify PR created successfully**
- URL: [PR URL]
- All info present
- CI triggered
- [ ] **Comment on issue**
"Submitted PR #[number]"
- [ ] **Monitor CI**
- All checks running
- Fix if any fail
### Ongoing
- [ ] **Respond to comments**
- Check daily
- Reply within 24-48 hours
- Be constructive
- [ ] **Make requested changes**
- Address feedback
- Push updates
- Mark comments resolved
- [ ] **Keep updated with main**
- Rebase if requested
- Resolve conflicts promptly
---
## Merge Preparation
### Before Merge
- [ ] **All reviews approved**
- Required approvals received
- No unresolved comments
- [ ] **CI passing**
- All checks green
- No failures
- [ ] **Up to date with main**
- No merge conflicts
- Latest changes incorporated
- [ ] **Final review**
- Re-check changes
- Verify quality
- Confirm ready
### After Merge
- [ ] **Update local repository**
```bash
git checkout main
git pull origin main
```
- [ ] **Delete feature branch**
```bash
git branch -d [branch-name]
git push origin --delete [branch-name]
```
- [ ] **Close related issues** (if not auto-closed)
- Issue #[number] closed
- [ ] **Celebrate!** 🎉
- Contribution merged
- Value added to project
- Experience gained
---
## Troubleshooting
### Common Issues
**CI Failing:**
- Check logs carefully
- Reproduce locally
- Fix and push update
- Don't wait for reviewer
**Merge Conflicts:**
- Rebase on main
- Resolve conflicts
- Test still passes
- Force push if needed
**Review Taking Long:**
- Be patient
- Maintainers are busy
- Polite ping after 1-2 weeks
- Don't take personally
**Changes Requested:**
- Thank reviewer
- Ask questions if unclear
- Make changes promptly
- Push updates
---
## Notes
[Personal notes, reminders, or considerations]
**Lessons Learned:**
[Note anything learned during this contribution for future reference]

117
plugin.lock.json Normal file
View File

@@ -0,0 +1,117 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:devkade/collaborator:skills/oss-contribution-framework",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "e7743a54f36837cb09f70bd4df4db3f907e9edac",
"treeHash": "4364d32c65eb2beee29ca4ae9a1e6abfe69ff99fa6e102326a817ebc92653713",
"generatedAt": "2025-11-28T10:16:19.629930Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "oss-contribution-framework",
"description": "Systematic 6-phase framework for contributing to open source projects from issue discovery to PR creation",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "84dce5bedc369ee3d7660ccca1dd174e0dc0fbe8bf8f41766a03d08e86ce1696"
},
{
"path": "SKILL.md",
"sha256": "2895077ce325560ae3954699acfe9b9cba0f81aea1fdae8d50afa50ba54707c4"
},
{
"path": "references/codebase-checklist.md",
"sha256": "9a6d6d686c9b53de9f4c97e8f176010190b30bd49a694bb636821cabd3a730ec"
},
{
"path": "references/pr-templates.md",
"sha256": "0d95d7fdf2b6d41dbb99cbc947300bb195105ad1b1e1524ee26a03f8c6e4426c"
},
{
"path": "references/contribution-tips.md",
"sha256": "432d33668998afa1ee3a21de871225b2ffefb2f29a944257643aa31cde4b96e0"
},
{
"path": "references/issue-patterns.md",
"sha256": "c0b46c1c59e2d22bf07c976f01f1a3fb85852dd14bbacea8b56b10fd445c61af"
},
{
"path": ".claude/commands/oss-contribution-framework.md",
"sha256": "4878a3690ced97425bf8bcbb79be75aae15f5a87378e30421aa707da8cdf96d9"
},
{
"path": ".claude/commands/oss:issue-analysis.md",
"sha256": "cf27b957dd3c51f02b6615d4745928cf0bf07fc4c73b9cc6e20a0cfbe977d210"
},
{
"path": ".claude/commands/oss:documentation-pr.md",
"sha256": "41a658b465ac7e72f743d60acd0498da0b9310a4cc4d910220157915178a3f28"
},
{
"path": ".claude/commands/oss:issue-code-mapping.md",
"sha256": "c84e0252d49934545c2ed55757f88cba31d5bd0a46ce0613475c35984a0f63cf"
},
{
"path": ".claude/commands/oss:issue-discovery.md",
"sha256": "ce3aa8d239f51b9a1761ecce90e74b6951152069a01b123b8be50a88b6f85d41"
},
{
"path": ".claude/commands/oss:codebase-exploration.md",
"sha256": "a10cba4f698fff425e162b8a10e7538e1b302773177a75131fc7e57db024d751"
},
{
"path": ".claude/commands/oss:solution-implementation.md",
"sha256": "874a828fa169958e4b56fb006ec559cc7e30a678f172238da36e7d87b235151b"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "411226c265216455097c2a28ae4d7032ca0b277adbd20f7fe20dce8fb9de537d"
},
{
"path": "skills/issue-discovery/SKILL.md",
"sha256": "73a9ab8fc10723bfdb9a770af431ad936eed44ad794d0a50d3b7f8a5bd14bb9a"
},
{
"path": "skills/issue-analysis/SKILL.md",
"sha256": "4dbc16987b4b3f754a3d2334028414da5bb65af9ff70364a4afdf83147c612ed"
},
{
"path": "skills/documentation-pr/SKILL.md",
"sha256": "655bc26dc8d1e434af2da6d5ebf7331e61d5a7153862165284cd18b8b8ba1f46"
},
{
"path": "skills/solution-implementation/SKILL.md",
"sha256": "135fe94a4dba324f038fbb994978e1e9a5073f0bb08a1f8a4f90f56431e6779e"
},
{
"path": "assets/templates/issue-analysis-template.md",
"sha256": "8bb3abd48abdcbf4a076633dbab1d8662c90e43b1b5fd79ce33a348daaeb577b"
},
{
"path": "assets/templates/codebase-notes-template.md",
"sha256": "d995f8cd50b7bcb95755b04a64d3f9e0f3928122721906b094e7361c5674cecc"
},
{
"path": "assets/templates/pr-checklist-template.md",
"sha256": "9fdbe51d3214760a36df9490996151dd1a8606f22b51a9cb150495310cd2b30b"
}
],
"dirSha256": "4364d32c65eb2beee29ca4ae9a1e6abfe69ff99fa6e102326a817ebc92653713"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

466
references/codebase-checklist.md Normal file
View File

@@ -0,0 +1,466 @@
# Codebase Exploration Checklist
Systematic checklist for understanding a new codebase.
## Initial Overview
### Documentation Review
- [ ] Read README.md thoroughly
- [ ] Review CONTRIBUTING.md for guidelines
- [ ] Check ARCHITECTURE.md or design docs
- [ ] Read recent CHANGELOG entries
- [ ] Review LICENSE and any legal requirements
- [ ] Check CODE_OF_CONDUCT.md
- [ ] Read SECURITY.md for vulnerability reporting
### Project Metadata
- [ ] Identify project purpose and scope
- [ ] Understand target users/audience
- [ ] Note primary programming language(s)
- [ ] Check framework/platform used
- [ ] Identify project maturity (alpha/beta/stable)
- [ ] Review release cadence
- [ ] Check activity level (recent commits)
---
## Repository Structure
### Directory Mapping
- [ ] Identify main source directory (src/, lib/, app/)
- [ ] Locate test directory (test/, tests/, __tests__/)
- [ ] Find documentation (docs/, doc/)
- [ ] Identify build output (dist/, build/, target/)
- [ ] Locate configuration files (config/, .config/)
- [ ] Find examples/samples (examples/, samples/)
- [ ] Check for scripts (scripts/, tools/, bin/)
### Organization Pattern
- [ ] Determine organization principle:
- [ ] By feature (user/, product/, order/)
- [ ] By layer (models/, views/, controllers/)
- [ ] By type (components/, utils/, services/)
- [ ] Hybrid approach
- [ ] Note any special directories
- [ ] Understand separation of concerns
- [ ] Identify public vs internal code
---
## Build System & Dependencies
### Package Management
- [ ] Identify package manager (npm, yarn, pip, cargo, maven)
- [ ] Locate package manifest (package.json, requirements.txt, Cargo.toml)
- [ ] Review dependencies and their purposes
- [ ] Check for peer dependencies
- [ ] Note any unusual or unfamiliar dependencies
- [ ] Check dependency versions and compatibility
### Build Configuration
- [ ] Identify build tool (webpack, vite, rollup, gradle)
- [ ] Locate build configuration files
- [ ] Understand build process
- [ ] Check for multiple build targets (dev, prod)
- [ ] Note output artifacts
- [ ] Identify entry points
### Setup & Installation
- [ ] Follow setup instructions in README
- [ ] Install dependencies successfully
- [ ] Verify development environment works
- [ ] Run development server/app
- [ ] Check for environment variable requirements
- [ ] Note any platform-specific setup
---
## Code Conventions
### Naming Conventions
- [ ] File naming pattern:
- [ ] kebab-case, PascalCase, snake_case, camelCase
- [ ] Extensions used (.ts, .tsx, .js, .jsx, .py, .rs)
- [ ] Directory naming pattern
- [ ] Component/class naming (PascalCase, etc)
- [ ] Function/method naming (camelCase, snake_case)
- [ ] Variable naming (camelCase, snake_case)
- [ ] Constant naming (UPPER_SNAKE_CASE, kConstant)
- [ ] Private member naming (_private, #private, __private)
- [ ] Boolean naming (isX, hasY, shouldZ)
### Code Style
- [ ] Indentation (tabs vs spaces, size)
- [ ] Line length limit
- [ ] Quote style (single, double)
- [ ] Semicolon usage
- [ ] Brace style (same line, new line)
- [ ] Import organization and ordering
- [ ] Blank line conventions
- [ ] Trailing comma usage
### Formatting Tools
- [ ] Check for .editorconfig
- [ ] Look for .prettierrc or prettier.config.js
- [ ] Check for .eslintrc or eslint.config.js
- [ ] Find other linter configs (.pylintrc, rustfmt.toml)
- [ ] Run formatter to see changes
- [ ] Run linter to check compliance
---
## Testing
### Test Framework
- [ ] Identify testing framework (Jest, pytest, JUnit, etc)
- [ ] Locate test configuration
- [ ] Understand test file naming convention
- [ ] Check test location pattern (co-located vs separate)
- [ ] Note test file extensions
### Test Structure
- [ ] Identify test structure pattern:
- [ ] describe/it (Jest, Mocha)
- [ ] test_ prefix (pytest)
- [ ] Test* classes (JUnit)
- [ ] #[test] attributes (Rust)
- [ ] Check for test helpers/utilities
- [ ] Review fixture patterns
- [ ] Understand mocking approach
- [ ] Note setup/teardown patterns
### Test Commands
- [ ] Run all tests: [command]
- [ ] Run specific test file: [command]
- [ ] Run with coverage: [command]
- [ ] Run in watch mode: [command]
- [ ] Run integration tests: [command]
- [ ] Run e2e tests: [command]
### Test Coverage
- [ ] Check coverage tool (nyc, coverage.py, tarpaulin)
- [ ] Find coverage configuration
- [ ] Identify coverage thresholds
- [ ] Locate coverage reports
- [ ] Check what's excluded from coverage
### Test Patterns
- [ ] Review 3-5 existing tests
- [ ] Identify assertion library/style
- [ ] Understand test data approach
- [ ] Note how mocks are created
- [ ] Check async test patterns
- [ ] Review error/exception testing
- [ ] Understand snapshot testing (if used)
---
## Development Workflow
### Running Locally
- [ ] Start development server: [command]
- [ ] Build for development: [command]
- [ ] Build for production: [command]
- [ ] Watch mode: [command]
- [ ] Clean build: [command]
### Code Quality
- [ ] Lint code: [command]
- [ ] Fix linting issues: [command]
- [ ] Format code: [command]
- [ ] Type check (if applicable): [command]
- [ ] Run pre-commit checks: [command]
### Git Workflow
- [ ] Check branching strategy (git flow, trunk-based)
- [ ] Understand branch naming convention
- [ ] Review commit message format
- [ ] Check for commit hooks (husky, pre-commit)
- [ ] Note PR/merge requirements
- [ ] Understand rebase vs merge policy
---
## CI/CD
### Continuous Integration
- [ ] Identify CI system (GitHub Actions, Travis, CircleCI)
- [ ] Locate CI configuration (.github/workflows/, .travis.yml)
- [ ] Review CI jobs/pipelines
- [ ] Understand what CI checks:
- [ ] Tests
- [ ] Linting
- [ ] Type checking
- [ ] Build
- [ ] Coverage
- [ ] Security scanning
- [ ] Note CI environment differences
- [ ] Check if CI runs on all branches or just some
### Deployment
- [ ] Check deployment process
- [ ] Identify deployment targets (npm, docker, cloud)
- [ ] Review deployment configuration
- [ ] Understand release process
- [ ] Note versioning strategy (semver, calver)
---
## Architecture & Patterns
### Overall Architecture
- [ ] Identify architectural pattern:
- [ ] MVC/MVP/MVVM
- [ ] Layered
- [ ] Clean Architecture
- [ ] Microservices
- [ ] Monolithic
- [ ] Component-based
- [ ] Understand data flow
- [ ] Identify key abstractions
- [ ] Note separation of concerns
- [ ] Check dependency direction
### Design Patterns
- [ ] Identify common design patterns used:
- [ ] Factory
- [ ] Strategy
- [ ] Observer
- [ ] Decorator
- [ ] Adapter
- [ ] Singleton
- [ ] Repository
- [ ] Service
- [ ] Note framework-specific patterns
- [ ] Understand composition patterns
### State Management (if applicable)
- [ ] Identify state management approach:
- [ ] Redux/Zustand/MobX
- [ ] Context API
- [ ] Local state
- [ ] Server state (React Query, SWR)
- [ ] Understand state organization
- [ ] Note where state lives
- [ ] Check for state persistence
### API/Interface Patterns
- [ ] Identify API style (REST, GraphQL, gRPC)
- [ ] Understand error handling pattern
- [ ] Note validation approach
- [ ] Check authentication/authorization pattern
- [ ] Review data serialization
---
## Language/Framework Specifics
### JavaScript/TypeScript
- [ ] Check ES version target
- [ ] Note module system (ESM, CommonJS)
- [ ] Review TypeScript config (if TS)
- [ ] Check for type definitions
- [ ] Note async patterns (Promise, async/await)
- [ ] Review bundler configuration
### Python
- [ ] Check Python version
- [ ] Note import style (absolute vs relative)
- [ ] Review requirements/dependencies
- [ ] Check for virtual environment usage
- [ ] Note async patterns (asyncio, threading)
- [ ] Review packaging configuration (setup.py, pyproject.toml)
### Rust
- [ ] Check Rust edition
- [ ] Review Cargo.toml features
- [ ] Note error handling pattern (Result, panic)
- [ ] Check for unsafe code usage
- [ ] Review trait usage patterns
- [ ] Note lifetime annotation style
### Go
- [ ] Check Go version
- [ ] Review module dependencies (go.mod)
- [ ] Note package organization
- [ ] Check error handling pattern
- [ ] Review interface usage
- [ ] Note concurrency patterns (goroutines, channels)
---
## Finding Similar Code
### Reference Examples
- [ ] Find examples of similar features
- [ ] Locate comparable components
- [ ] Identify similar bug fixes
- [ ] Review similar tests
- [ ] Check similar API endpoints
- [ ] Find analogous utilities
### Search Strategies
```bash
# Find similar files
find . -name "*[similar-name]*"
# Find similar patterns
rg "pattern" --type [lang]
# Find similar classes/functions
rg "class.*Name|function.*Name"
# Find usages
rg "functionName\("
# Find similar tests
rg "test.*similar|describe.*Similar"
```
---
## Code Reading
### Entry Points
- [ ] Identify main entry point (main.js, __main__.py, main.rs)
- [ ] Find route definitions (for web apps)
- [ ] Locate command definitions (for CLI tools)
- [ ] Identify public API (for libraries)
- [ ] Find initialization code
### Core Components
- [ ] Identify 3-5 most important modules
- [ ] Understand their responsibilities
- [ ] Note their relationships
- [ ] Review their interfaces
- [ ] Check their dependencies
### Code Flow
- [ ] Trace a simple user action
- [ ] Follow a typical request path
- [ ] Understand data transformations
- [ ] Note side effects
- [ ] Identify external calls
---
## Documentation
### Inline Documentation
- [ ] Check documentation style (JSDoc, docstrings, rustdoc)
- [ ] Review documentation coverage
- [ ] Note documentation patterns
- [ ] Check for examples in docs
- [ ] Review parameter documentation
### External Documentation
- [ ] Check for API documentation
- [ ] Review user guides
- [ ] Find developer guides
- [ ] Look for architecture diagrams
- [ ] Check for decision records (ADRs)
---
## Security & Performance
### Security Practices
- [ ] Check input validation patterns
- [ ] Review authentication approach
- [ ] Understand authorization checks
- [ ] Note data sanitization
- [ ] Check for security warnings in dependencies
- [ ] Review secrets management
### Performance Considerations
- [ ] Identify performance-critical paths
- [ ] Check for caching strategies
- [ ] Note optimization patterns
- [ ] Review resource management
- [ ] Check for profiling tools
---
## Community & Contribution
### Communication Channels
- [ ] Find discussion forum/Discord/Slack
- [ ] Locate issue tracker
- [ ] Check for mailing list
- [ ] Find meeting notes (if any)
- [ ] Review RFCs or proposals
### Contribution Process
- [ ] Review issue labels and meanings
- [ ] Understand PR template requirements
- [ ] Check review process
- [ ] Note testing requirements
- [ ] Understand merge criteria
---
## Project-Specific Notes
### Custom Conventions
- [ ] Note any unusual patterns
- [ ] Document project-specific terms
- [ ] Record special requirements
- [ ] Note gotchas or common mistakes
- [ ] List helpful resources
### Tool-Specific Setup
- [ ] IDE/editor configuration
- [ ] Debugging setup
- [ ] Testing utilities
- [ ] Code generation tools
- [ ] Development aids
---
## Completion Checklist
Before considering exploration complete:
- [ ] Can navigate the codebase confidently
- [ ] Understand main architecture and patterns
- [ ] Know where to find things
- [ ] Can run, build, and test locally
- [ ] Understand contribution workflow
- [ ] Have found reference examples
- [ ] Know project conventions
- [ ] Can ask informed questions
- [ ] Ready to start implementation
---
## Notes Template
Use this to record your findings:
```markdown
# Codebase Exploration Notes: [Project Name]
**Date:** [date]
**For Issue:** #[number]
## Quick Reference
- Main language: [language]
- Framework: [framework]
- Test command: [command]
- Dev server: [command]
## Structure
[Key directory map]
## Conventions
[Important patterns to follow]
## Similar Code
[Reference examples for my work]
## Questions
[Things still unclear]
## Ready to Code
[Specific files/functions I'll modify]
```

783
references/contribution-tips.md Normal file
View File

@@ -0,0 +1,783 @@
# Contribution Tips & Best Practices
Project-agnostic tips and insights for successful open source contributions.
## General Principles
### Start Small
**Why:**
- Build trust with maintainers
- Learn project workflow
- Understand conventions
- Reduce risk of wasted effort
**Good first contributions:**
- Documentation improvements
- Typo fixes
- Simple bug fixes
- Test additions
- Small feature additions
**Progression:**
```
First PR: Docs/typo fix (learn workflow)
↓
Second PR: Small bug fix (learn codebase)
↓
Third PR: Medium feature (demonstrate ability)
↓
Ongoing: Complex work (trusted contributor)
```
### Communicate Early and Often
**Before starting work:**
- Comment on issue: "I'd like to work on this"
- Outline your approach: "I plan to..."
- Ask questions: "Should I... or ...?"
- Wait for confirmation: "Sounds good, go ahead!"
**During implementation:**
- Share progress on complex issues
- Ask when blocked
- Discuss tradeoffs
- Seek early feedback (draft PRs)
**After submission:**
- Respond to comments promptly
- Be open to feedback
- Explain your reasoning
- Thank reviewers
**Why it matters:**
- Avoids duplicate work
- Prevents wrong approach
- Builds relationships
- Shows professionalism
### Respect Maintainer Time
**Remember:**
- Maintainers are often volunteers
- They have limited time
- They manage many issues/PRs
- They have context you don't
**How to respect their time:**
✅ **Do:**
- Make PR easy to review (small, focused, clear)
- Provide context in description
- Address review comments promptly
- Self-review before submitting
- Follow project conventions exactly
- Ensure CI passes before requesting review
❌ **Don't:**
- Submit huge PRs without warning
- Ignore review comments
- Argue about style preferences
- Submit broken PRs
- Ping repeatedly for review
- Take criticism personally
---
## Technical Excellence
### Follow Conventions Religiously
**Why it matters:**
- Consistency is crucial
- Shows respect for project
- Makes code maintainable
- Easier to review
**What to match:**
- Code style and formatting
- Naming conventions
- File organization
- Comment style
- Test patterns
- Commit message format
**How to learn conventions:**
1. Read CONTRIBUTING.md
2. Study existing code
3. Run linters/formatters
4. Ask if unclear
**Rule:** When in Rome, do as Romans do - even if you disagree.
### Write Clear Commit Messages
**Good format:**
```
type(scope): brief description (50 chars max)
Longer explanation of what and why (not how).
Wrap at 72 characters.
- Bullet points ok
- For multiple points
Fixes #123
```
**Types:**
- feat: New feature
- fix: Bug fix
- docs: Documentation
- style: Formatting
- refactor: Code restructuring
- test: Tests
- chore: Maintenance
**Examples:**
✅ **Good:**
```
fix(auth): prevent session hijacking via cookie theft
Previously, session cookies didn't have SameSite attribute,
allowing CSRF attacks. Now sets SameSite=Strict for all
session cookies.
Fixes #456
```
❌ **Bad:**
```
fix bug
```
✅ **Good:**
```
feat(api): add pagination to user list endpoint
Implements cursor-based pagination for /api/users endpoint
to handle large user bases efficiently. Defaults to 20 items
per page, configurable via ?limit parameter.
- Add pagination logic
- Update API tests
- Document in API reference
Closes #789
```
❌ **Bad:**
```
added feature
```
### Test Thoroughly
**Test types to consider:**
**Unit tests:**
- Test individual functions
- Fast and focused
- Mock dependencies
- Cover edge cases
**Integration tests:**
- Test component interaction
- More realistic
- Fewer mocks
- Verify integration points
**E2E tests (when needed):**
- Test full user workflows
- Catch integration issues
- Slower but comprehensive
**What to test:**
- ✅ Happy path (normal case)
- ✅ Edge cases (empty, null, max, min)
- ✅ Error cases (invalid input, failures)
- ✅ Integration (works with other features)
- ❌ Implementation details
- ❌ Third-party code
**Test quality:**
```javascript
// ❌ Bad: Tests implementation details
test('should call handleClick', () => {
expect(handleClick).toHaveBeenCalled()
})
// ✅ Good: Tests behavior
test('should increment counter when clicked', () => {
render(<Counter />)
click(getByRole('button'))
expect(getByText('Count: 1')).toBeInTheDocument()
})
```
### Handle Edge Cases
**Common edge cases:**
- Empty input: `[]`, `""`, `null`, `undefined`
- Boundary values: 0, 1, max, min, -1
- Special characters: quotes, newlines, unicode
- Large input: Performance with big datasets
- Concurrent access: Race conditions
- Network issues: Timeouts, failures
- Permissions: Unauthorized access
**How to find edge cases:**
1. Think about input constraints
2. Consider "what if..." scenarios
3. Review similar code for bugs
4. Look at issue tracker
5. Ask in PR description
**Example:**
```javascript
// Feature: Format currency
function formatCurrency(amount) {
// Edge cases to consider:
// - amount is negative
// - amount is 0
// - amount is very large
// - amount has many decimals
// - amount is null/undefined
// - amount is not a number
if (amount == null) return '$0.00'
if (typeof amount !== 'number') {
throw new TypeError('amount must be a number')
}
return `$${amount.toFixed(2)}`
}
```
---
## Code Review Process
### Self-Review First
**Before requesting review:**
1. **Review your own changes:**
- Read through entire diff
- Check for debugging code
- Remove commented code
- Verify no secrets committed
- Check for todos
2. **Test thoroughly:**
- All tests pass
- Linting passes
- Manual testing done
- CI passes
3. **Check quality:**
- Code is clear
- Comments added where needed
- No obvious bugs
- Follows conventions
4. **Verify completeness:**
- All requirements met
- Edge cases handled
- Documentation updated
- Tests added
### Responding to Feedback
**Types of review comments:**
**1. Bugs/Issues (must fix):**
```
Reviewer: "This will crash if data is null"
✅ Good response:
"Good catch! Fixed in commit abc123. Also added a test
to prevent regression."
```
**2. Style/Conventions (must fix):**
```
Reviewer: "Variables should be camelCase per style guide"
✅ Good response:
"Fixed! Updated all variables to match convention."
❌ Bad response:
"I prefer snake_case because..."
[Don't argue about project conventions]
```
**3. Suggestions (evaluate):**
```
Reviewer: "Could simplify this with Array.reduce()"
✅ Good response:
"Great idea! Changed to use reduce. Much cleaner."
or
"I considered reduce, but opted for explicit loop for
clarity since this is a critical path. Happy to change
if you feel strongly."
```
**4. Questions (answer):**
```
Reviewer: "Why did you choose approach X over Y?"
✅ Good response:
"Chose X because [reason]. Y has issue with [problem].
I can add a comment explaining this."
```
**5. Nitpicks (optional):**
```
Reviewer: "Nit: could extract this to a variable"
✅ Good responses:
"Done!"
or
"Good point, but keeping inline for readability here."
```
**General tips:**
- Thank reviewers for feedback
- Don't take criticism personally
- Explain reasoning clearly
- Be open to learning
- Fix quickly and push updates
- Resolve threads when addressed
### When Reviewers Disagree
**If you disagree with feedback:**
1. **Understand their perspective:**
"Could you help me understand your concern?"
2. **Explain your reasoning:**
"I chose X because [reason]. Does that address your concern?"
3. **Suggest compromise:**
"What if we [alternative approach]?"
4. **Defer to maintainer:**
"I see your point. Happy to change it."
**Remember:**
- They know the project better
- They'll maintain your code
- Consistency matters more than "best" approach
- Battles aren't worth fighting
### Dealing with Slow Reviews
**If no response after reasonable time:**
**Week 1:**
- Wait patiently
- Ensure CI passes
- Fix any issues
**Week 2:**
- Polite ping: "Hi! Just checking if you had a chance to review this. No rush!"
**Week 3:**
- Check if action needed from you
- Ask if changes are needed
**Week 4+:**
- Consider if project is active
- May need to move on
- Don't take it personally
**Don't:**
- Ping daily
- Demand attention
- Complain
- Give ultimatums
---
## Project Types & Strategies
### Large Projects
**Characteristics:**
- Many contributors
- Formal processes
- Longer review times
- Higher standards
**Strategy:**
- Read guidelines carefully
- Start with small issues
- Be patient with reviews
- Follow processes exactly
- Engage with community
**Examples:**
- Linux kernel
- Kubernetes
- React
- VS Code
### Small Projects
**Characteristics:**
- Few maintainers
- Informal processes
- Direct communication
- May need more convincing
**Strategy:**
- Be more helpful
- Fix multiple small issues
- Suggest improvements
- Be understanding of limited time
- Build relationship
**Examples:**
- Most projects on GitHub
- Single-maintainer tools
- Niche libraries
### Corporate-Backed Projects
**Characteristics:**
- Paid maintainers
- Clear roadmap
- Professional processes
- May have legal requirements
**Strategy:**
- Follow process strictly
- Sign CLA if required
- Align with roadmap
- Professional communication
- Expect formal reviews
**Examples:**
- Google's projects (Angular, Tensorflow)
- Facebook's projects (React, Jest)
- Microsoft's projects (TypeScript, .NET)
### Community-Driven Projects
**Characteristics:**
- Volunteer-run
- Democratic decisions
- May be slower
- Community matters
**Strategy:**
- Engage in discussions
- Understand consensus
- Be part of community
- Contribute beyond code
- Be patient
**Examples:**
- Python
- Rust
- Many CNCF projects
---
## Common Mistakes
### Technical Mistakes
❌ **Skipping tests**
- "Tests are someone else's job"
- Tests are requirements
❌ **Not testing locally**
- "CI will catch it"
- CI is not your test runner
❌ **Scope creep**
- "While I'm here, I'll also..."
- Keep PRs focused
❌ **Ignoring conventions**
- "My way is better"
- Consistency > personal preference
❌ **Over-engineering**
- "Let me add 5 new abstractions"
- Simplicity wins
❌ **Copy-pasting without understanding**
- "This code looks similar"
- Understand before copying
### Process Mistakes
❌ **Not claiming issues**
- Start work without commenting
- Someone else might also be working
❌ **Going silent**
- No response to review comments
- Communicate even if busy
❌ **Arguing unnecessarily**
- Defend every decision
- Pick battles wisely
❌ **Huge first PR**
- Submit 2000 line PR as first contribution
- Start small
❌ **Not reading docs**
- Miss CONTRIBUTING.md guidelines
- Read docs first
### Communication Mistakes
❌ **Demanding**
- "When will you review this?"
- Be patient and polite
❌ **Defensive**
- "You're wrong because..."
- Stay humble and open
❌ **Ghosting**
- No response after review comments
- Respond even if busy
❌ **Over-committing**
- "I'll fix all 20 issues"
- Finish one first
---
## Building Reputation
### Become a Trusted Contributor
**How to build trust:**
1. **Consistent quality:**
- Well-tested code
- Clear communication
- Follow conventions
- Thoughtful changes
2. **Reliable:**
- Finish what you start
- Respond promptly
- Follow through on commitments
3. **Helpful:**
- Answer questions
- Help other contributors
- Improve docs
- Triage issues
4. **Long-term:**
- Multiple contributions
- Sustained engagement
- Show commitment
**Benefits:**
- Faster reviews
- More trust in changes
- Input on direction
- Possible maintainer role
- References for jobs
### Contributing Beyond Code
**Other valuable contributions:**
**Documentation:**
- Improve README
- Add examples
- Fix errors
- Write tutorials
**Issue triage:**
- Reproduce bugs
- Add missing info
- Label appropriately
- Close duplicates
**Code review:**
- Review others' PRs
- Provide helpful feedback
- Catch issues
- Share knowledge
**Community:**
- Answer questions
- Welcome newcomers
- Moderate discussions
- Organize events
**All of these build reputation!**
---
## Career Benefits
### OSS as Portfolio
**Contributions show:**
- Real coding ability
- Can work on production code
- Understand team dynamics
- Write maintainable code
- Take feedback well
**Better than personal projects because:**
- Code actually used
- Reviewed by experts
- Part of real system
- Demonstrates collaboration
### Learning Opportunities
**You learn:**
- How real projects are structured
- Best practices and patterns
- Code review process
- Working with others
- New technologies
- How to write maintainable code
### Networking
**Connections made through OSS:**
- Maintainers (often senior engineers)
- Other contributors
- Users of the project
- Potential employers
### Job Opportunities
**Many developers get jobs through:**
- OSS contributions on resume
- Connections made
- Direct recruiting from companies
- Demonstrable skills
---
## Staying Motivated
### Set Realistic Goals
**Start with:**
- 1 small PR per month
- Or: contribute to 1 project regularly
- Or: fix bugs you encounter
**Don't:**
- Try to contribute to 10 projects at once
- Commit to large features right away
- Burn yourself out
### Find Projects You Care About
**Best contributions come from:**
- Tools you use daily
- Problems you've personally faced
- Technologies you want to learn
- Communities you value
**Don't contribute just for resume.**
### Celebrate Wins
**Every PR merged is a win:**
- First PR merged? 🎉
- Complex feature shipped? 🎉
- Bug you found fixed? 🎉
- Doc helped someone? 🎉
**Track your contributions:**
- Keep list of merged PRs
- Note what you learned
- Reflect on growth
### Handle Rejection
**Not all PRs will be merged:**
- Timing might be wrong
- Different vision
- Not aligned with goals
- Technical concerns
**How to handle rejection:**
- Don't take personally
- Understand reasoning
- Learn from feedback
- Try different project
- Ask how to improve
**Rejection is normal and ok!**
---
## Resources
### Learning More
**Guides:**
- "How to Contribute to Open Source" (opensource.guide)
- Project-specific CONTRIBUTING.md files
- "First Timers Only" (firsttimersonly.com)
**Finding Projects:**
- github.com/topics/good-first-issue
- up-for-grabs.net
- Projects you already use
- Ask maintainers for suggestions
**Communities:**
- Project Discord/Slack channels
- OSS contributor forums
- Local meetups
- Online communities
### Getting Help
**When stuck:**
1. Search existing issues/docs
2. Ask in project's chat/forum
3. Comment on issue
4. Reach out to maintainers
5. Ask in general OSS communities
**Don't suffer in silence!**
---
## Final Thoughts
### Key Principles
1. **Start small** - Build up to complex work
2. **Communicate** - Early, often, respectfully
3. **Be patient** - Reviews take time
4. **Stay humble** - You're always learning
5. **Think long-term** - Build relationships
6. **Have fun** - Enjoy the process!
### Remember
- Every expert was once a beginner
- Every project welcomes good contributions
- Every maintainer appreciates help
- Every bug fixed helps users
- Every contribution matters
**Good luck with your open source journey! 🚀**

714
references/issue-patterns.md Normal file
View File

@@ -0,0 +1,714 @@
# Issue Patterns Reference
Common issue types and specialized approaches for each.
## Bug Reports
### Characteristics
- Something is broken
- Current behavior doesn't match expected
- Often includes error messages
- May have reproduction steps
### Analysis Pattern
**1. Reproduce**
- Follow reproduction steps exactly
- Verify bug exists
- Note environment details
**2. Isolate**
- Minimal test case
- Remove unrelated factors
- Identify triggering conditions
**3. Locate**
- Find where error occurs
- Trace backwards to cause
- Identify root cause vs symptoms
**4. Fix Strategy**
- Fix root cause, not symptoms
- Handle similar edge cases
- Don't break working cases
- Add regression test
### Common Bug Patterns
**Null/Undefined Errors:**
```javascript
// Bug: Crashes when data is null
function process(data) {
return data.value // TypeError if data is null
}
// Fix: Handle null case
function process(data) {
if (!data) return defaultValue
return data.value
}
// Test
expect(process(null)).toBe(defaultValue)
```
**Off-by-One Errors:**
```python
# Bug: Skips last element
for i in range(len(arr) - 1):
process(arr[i])
# Fix
for i in range(len(arr)):
process(arr[i])
# Or better
for item in arr:
process(item)
```
**Race Conditions:**
```javascript
// Bug: State changes between check and use
if (cache.has(key)) {
return cache.get(key) // Might be deleted by now
}
// Fix: Get once, check result
const value = cache.get(key)
if (value !== undefined) {
return value
}
```
**Input Validation:**
```javascript
// Bug: No validation
function divide(a, b) {
return a / b // Division by zero
}
// Fix: Validate inputs
function divide(a, b) {
if (b === 0) {
throw new Error('Division by zero')
}
return a / b
}
```
---
## Feature Requests
### Characteristics
- Request for new functionality
- Describes user need
- May include use cases
- May have mockups/examples
### Analysis Pattern
**1. Understand Need**
- Who needs this?
- What problem does it solve?
- What are use cases?
- Why existing features insufficient?
**2. Design API/Interface**
- How will users interact?
- What's the simplest interface?
- Consistent with existing features?
- Extensible for future needs?
**3. Plan Implementation**
- Where does it fit architecturally?
- What components affected?
- Data model changes needed?
- Breaking changes?
**4. Implementation Strategy**
- Start with minimal viable version
- Add polish incrementally
- Get feedback early
- Document well
### Feature Types
**UI Feature:**
```markdown
**Checklist:**
- [ ] Component implementation
- [ ] State management
- [ ] Event handling
- [ ] Styling
- [ ] Responsive design
- [ ] Accessibility
- [ ] Loading states
- [ ] Error states
- [ ] User feedback (success/error messages)
```
**API Endpoint:**
```markdown
**Checklist:**
- [ ] Route definition
- [ ] Request validation
- [ ] Business logic
- [ ] Response formatting
- [ ] Error handling
- [ ] Authentication/authorization
- [ ] Rate limiting (if needed)
- [ ] API documentation
- [ ] Integration tests
```
**CLI Command:**
```markdown
**Checklist:**
- [ ] Command definition
- [ ] Argument parsing
- [ ] Validation
- [ ] Core logic
- [ ] Output formatting
- [ ] Error messages
- [ ] Help text
- [ ] Examples in docs
```
**Library Function:**
```markdown
**Checklist:**
- [ ] Function signature design
- [ ] Input validation
- [ ] Core implementation
- [ ] Error handling
- [ ] Documentation (JSDoc/docstrings)
- [ ] Usage examples
- [ ] Type definitions
- [ ] Backwards compatibility
```
---
## Documentation Issues
### Characteristics
- Missing or unclear docs
- Outdated information
- Requests for examples
- Typos or formatting
### Analysis Pattern
**1. Identify Gap**
- What's missing?
- Who's the audience?
- What level of detail?
- Where should it live?
**2. Research**
- Understand the feature fully
- Find code examples
- Check similar docs
- Verify current behavior
**3. Write**
- Clear and concise
- Examples included
- Proper formatting
- Links to related docs
**4. Verify**
- Technically accurate
- Examples work
- No broken links
- Proper grammar/spelling
### Documentation Types
**Tutorials:**
```markdown
**Structure:**
1. What you'll build
2. Prerequisites
3. Step-by-step instructions
4. Expected results
5. Next steps
**Style:**
- Conversational
- Hand-holding
- Complete working example
- Learn by doing
```
**How-To Guides:**
```markdown
**Structure:**
1. Problem statement
2. Solution approach
3. Step-by-step
4. Variations/alternatives
**Style:**
- Task-oriented
- Practical
- Assumes some knowledge
- Shows best practices
```
**Reference:**
```markdown
**Structure:**
1. Function/API signature
2. Parameters
3. Return value
4. Errors/exceptions
5. Examples
6. See also
**Style:**
- Precise
- Complete
- Technical
- Searchable
```
**Conceptual:**
```markdown
**Structure:**
1. Overview
2. Key concepts
3. How it works
4. When to use
5. Related topics
**Style:**
- Explanatory
- Big picture
- Theory and context
- Understanding-focused
```
---
## Refactoring Issues
### Characteristics
- Code quality improvement
- No behavior change
- Technical debt
- Maintainability focus
### Analysis Pattern
**1. Identify Problems**
- Code smells
- Duplication
- Complexity
- Poor naming
- Tight coupling
**2. Ensure Test Coverage**
- Tests exist for current behavior
- Tests are comprehensive
- Tests will catch regressions
**3. Plan Incremental Steps**
- Small, safe transformations
- Each step leaves code working
- Can pause/resume anytime
**4. Execute Carefully**
- One refactoring at a time
- Run tests after each step
- Commit working states
- Don't mix with feature work
### Refactoring Patterns
**Extract Function:**
```javascript
// Before: Long complex function
function processOrder(order) {
// 50 lines of code
// mixing concerns
}
// After: Extracted smaller functions
function processOrder(order) {
validateOrder(order)
const items = prepareItems(order.items)
const total = calculateTotal(items)
return createInvoice(order, items, total)
}
function validateOrder(order) { /* ... */ }
function prepareItems(items) { /* ... */ }
function calculateTotal(items) { /* ... */ }
function createInvoice(order, items, total) { /* ... */ }
```
**Remove Duplication:**
```python
# Before: Duplicated logic
def process_user_data(data):
if not data:
raise ValueError("Invalid data")
# process...
def process_order_data(data):
if not data:
raise ValueError("Invalid data")
# process...
# After: Extracted common logic
def validate_data(data):
if not data:
raise ValueError("Invalid data")
def process_user_data(data):
validate_data(data)
# process...
def process_order_data(data):
validate_data(data)
# process...
```
**Improve Naming:**
```javascript
// Before: Unclear names
function calc(x, y) {
const t = x * y
const d = t * 0.1
return t - d
}
// After: Clear names
function calculateTotalWithDiscount(price, quantity) {
const subtotal = price * quantity
const discount = subtotal * 0.1
return subtotal - discount
}
```
**Reduce Complexity:**
```javascript
// Before: Deep nesting
function process(data) {
if (data) {
if (data.items) {
if (data.items.length > 0) {
// process
}
}
}
}
// After: Early returns
function process(data) {
if (!data) return
if (!data.items) return
if (data.items.length === 0) return
// process
}
```
---
## Performance Issues
### Characteristics
- Something is slow
- Resource usage high
- Scalability problems
- May include benchmarks
### Analysis Pattern
**1. Measure**
- Reproduce performance issue
- Measure current performance
- Profile to find bottleneck
- Get baseline numbers
**2. Identify Cause**
- Algorithm complexity
- Unnecessary work
- Resource leaks
- Inefficient data structures
**3. Optimize**
- Fix the bottleneck
- Use better algorithm
- Cache when appropriate
- Lazy load when possible
**4. Verify**
- Measure improvement
- Check correctness maintained
- Verify no regressions
- Document tradeoffs
### Performance Patterns
**Algorithm Optimization:**
```javascript
// Before: O(n²)
function findDuplicates(arr) {
const dupes = []
for (let i = 0; i < arr.length; i++) {
for (let j = i + 1; j < arr.length; j++) {
if (arr[i] === arr[j]) {
dupes.push(arr[i])
}
}
}
return dupes
}
// After: O(n)
function findDuplicates(arr) {
const seen = new Set()
const dupes = new Set()
for (const item of arr) {
if (seen.has(item)) {
dupes.add(item)
}
seen.add(item)
}
return Array.from(dupes)
}
```
**Caching:**
```javascript
// Before: Recalculates every time
function expensiveCalculation(data) {
// Heavy computation
return result
}
// After: Cache results
const cache = new Map()
function expensiveCalculation(data) {
const key = JSON.stringify(data)
if (cache.has(key)) {
return cache.get(key)
}
const result = /* heavy computation */
cache.set(key, result)
return result
}
```
**Lazy Loading:**
```javascript
// Before: Load everything upfront
const data = loadAllData() // Slow!
// After: Load on demand
let data = null
function getData() {
if (!data) {
data = loadAllData()
}
return data
}
```
---
## Security Issues
### Characteristics
- Security vulnerability
- Potential exploit
- Missing validation
- Unsafe practices
### Analysis Pattern
**1. Assess Severity**
- What can attacker do?
- What data is at risk?
- Who is affected?
- How easy to exploit?
**2. Identify Root Cause**
- Missing validation?
- Unsafe API usage?
- Incorrect logic?
- Outdated dependency?
**3. Fix Securely**
- Validate all inputs
- Use safe APIs
- Follow security best practices
- Don't roll your own crypto
**4. Verify Fix**
- Test exploit no longer works
- Check similar code
- Add security tests
- Consider security review
### Security Patterns
**Input Validation:**
```javascript
// Before: No validation
app.post('/user/:id', (req, res) => {
const query = `SELECT * FROM users WHERE id = ${req.params.id}`
db.query(query) // SQL injection!
})
// After: Validated and parameterized
app.post('/user/:id', (req, res) => {
const id = parseInt(req.params.id, 10)
if (isNaN(id)) {
return res.status(400).json({ error: 'Invalid ID' })
}
const query = 'SELECT * FROM users WHERE id = ?'
db.query(query, [id]) // Safe
})
```
**XSS Prevention:**
```javascript
// Before: Direct HTML insertion
element.innerHTML = userInput // XSS!
// After: Escaped text
element.textContent = userInput // Safe
// Or use framework's escaping
element.innerHTML = escapeHtml(userInput)
```
**Authorization:**
```javascript
// Before: No auth check
app.delete('/user/:id', (req, res) => {
deleteUser(req.params.id) // Anyone can delete!
})
// After: Check permissions
app.delete('/user/:id', requireAuth, (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).json({ error: 'Forbidden' })
}
deleteUser(req.params.id)
})
```
---
## CI/CD Issues
### Characteristics
- Build failures
- Test flakiness
- Deployment problems
- Pipeline configuration
### Analysis Pattern
**1. Reproduce Locally**
- Can you reproduce the issue?
- Environment differences?
- Missing dependencies?
**2. Identify Cause**
- Check CI logs
- Look for error messages
- Compare with working runs
- Check recent changes
**3. Fix**
- Update configuration
- Fix flaky tests
- Add missing dependencies
- Improve reliability
**4. Verify**
- Passes consistently
- Doesn't break other jobs
- Works across environments
### CI/CD Patterns
**Flaky Test Fix:**
```javascript
// Before: Flaky due to timing
test('updates after delay', () => {
triggerUpdate()
expect(getValue()).toBe(newValue) // Sometimes fails
})
// After: Proper async handling
test('updates after delay', async () => {
triggerUpdate()
await waitFor(() => expect(getValue()).toBe(newValue))
})
```
**Environment-Specific Fix:**
```javascript
// Before: Assumes specific OS
const path = '/usr/local/bin' // Fails on Windows
// After: Cross-platform
const path = require('path').join(os.homedir(), 'bin')
```
---
## Dependency Updates
### Characteristics
- Upgrade library version
- Fix security vulnerability
- Get new features
- Maintenance
### Analysis Pattern
**1. Check Changes**
- Read changelog
- Review breaking changes
- Check migration guide
- Assess impact
**2. Update**
- Update package version
- Update code if needed
- Update tests
- Update docs
**3. Test Thoroughly**
- All tests pass
- Manual testing
- Check for regressions
- Verify new version works
**4. Document**
- Note breaking changes
- Update dependencies list
- Mention in changelog
---
## Using This Reference
When analyzing an issue:
1. Identify issue type
2. Read corresponding pattern
3. Follow analysis checklist
4. Apply relevant code patterns
5. Adapt to specific context
Each project and issue is unique - use these as starting points, not rigid rules.

762
references/pr-templates.md Normal file
View File

@@ -0,0 +1,762 @@
# PR Templates Reference
Collection of PR templates for various project types and change types.
## Universal PR Template
Use this as a base for any PR:
```markdown
## Description
[Clear description of what this PR does and why]
## Changes Made
- [Change 1]
- [Change 2]
- [Change 3]
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring
- [ ] Performance improvement
- [ ] Test coverage improvement
- [ ] Build/CI improvement
- [ ] Chore/maintenance
## Related Issue
Fixes #[issue-number]
## How to Test
1. [Step 1]
2. [Step 2]
3. [Verify expected behavior]
## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published
```
---
## Bug Fix Template
```markdown
## Bug Fix: [Brief Description]
### Problem
[Describe the bug that was fixed]
**Symptoms:**
- [What users experienced]
- [Error messages, if any]
**Root Cause:**
[What was causing the bug]
### Solution
[Explain how the fix addresses the root cause]
### Changes Made
- **Modified:** `path/to/file.ext`
- [Specific change made]
- **Added:** Test case for regression prevention
- **Updated:** Documentation (if applicable)
### Testing
**Reproduction steps (before fix):**
1. [Step that triggered bug]
2. [Expected: X, Actual: Y]
**Verification steps (after fix):**
1. [Same steps]
2. [Now works correctly]
**Regression test:**
- [ ] Added test that fails without fix
- [ ] Test passes with fix
- [ ] Related tests still pass
### Related Issue
Fixes #[issue-number]
### Checklist
- [ ] Root cause identified and fixed (not just symptoms)
- [ ] Regression test added
- [ ] Similar edge cases considered
- [ ] No new warnings introduced
- [ ] All tests pass locally
- [ ] Documentation updated if behavior changed
```
---
## Feature Addition Template
```markdown
## Feature: [Feature Name]
### Summary
[2-3 sentences: What this feature does and why it's valuable]
### Motivation
**User Need:**
[What problem does this solve?]
**Use Cases:**
1. [Use case 1]
2. [Use case 2]
### Implementation
**Approach:**
[High-level description of implementation approach]
**Key Components:**
- **[Component 1]** - [Purpose]
- **[Component 2]** - [Purpose]
**Design Decisions:**
- [Decision 1]: [Rationale]
- [Decision 2]: [Rationale]
### Changes Made
**Core Implementation:**
- `path/to/new/file.ext` - [What it does]
- `path/to/modified/file.ext` - [Changes made]
**Tests:**
- `path/to/test/file.ext` - [What's tested]
**Documentation:**
- Updated README with usage examples
- Added API documentation
- Updated CHANGELOG
### Usage Example
```[language]
// Example of how to use the new feature
const result = newFeature(input)
```
### API (if applicable)
**New Functions/Methods:**
```[language]
/**
* [Description]
* @param {Type} param - [Description]
* @returns {Type} [Description]
*/
function newFunction(param) {
// ...
}
```
### Testing
**Test Coverage:**
- [ ] Happy path
- [ ] Edge cases: [list specific ones]
- [ ] Error cases: [list specific ones]
- [ ] Integration with existing features
**Manual Testing:**
1. [How to try the feature]
2. [Expected result]
### Related Issue
Fixes #[issue-number]
### Breaking Changes
[If any, describe them. Otherwise state "None"]
### Future Enhancements
[Optional: Ideas for future improvements that are out of scope for this PR]
### Checklist
- [ ] Feature is complete and working
- [ ] Follows project conventions
- [ ] Tests added and passing
- [ ] Documentation updated
- [ ] Examples provided
- [ ] No performance regressions
- [ ] Backwards compatible (or breaking changes documented)
```
---
## Refactoring Template
```markdown
## Refactoring: [What's Being Refactored]
### Motivation
**Current Problems:**
- [Problem 1: e.g., code duplication]
- [Problem 2: e.g., tight coupling]
- [Problem 3: e.g., difficult to test]
**Benefits of Refactoring:**
- [Benefit 1: e.g., improved maintainability]
- [Benefit 2: e.g., better testability]
- [Benefit 3: e.g., clearer separation of concerns]
### Changes Made
**Refactored Files:**
- `path/to/file.ext`
- Before: [What it was]
- After: [What it is now]
- Improvements: [Specific improvements]
### Refactoring Type
- [ ] Extract function/method
- [ ] Extract class/module
- [ ] Rename for clarity
- [ ] Remove duplication
- [ ] Simplify logic
- [ ] Improve structure
- [ ] Update patterns to modern practices
### Behavior Preservation
**Guarantees:**
- [ ] All existing tests pass
- [ ] No functional changes
- [ ] Same inputs produce same outputs
- [ ] No API changes (for libraries)
**Evidence:**
- Test suite: [X/X passing]
- Coverage: [maintained or improved]
- Manual testing: [verified key workflows]
### Code Quality Metrics (optional)
**Before:**
- Lines of code: [number]
- Cyclomatic complexity: [number]
- Duplication: [percentage]
**After:**
- Lines of code: [number]
- Cyclomatic complexity: [number]
- Duplication: [percentage]
### Related Issue
Addresses #[issue-number]
### Checklist
- [ ] No behavior changes
- [ ] All tests pass
- [ ] No new warnings
- [ ] Test coverage maintained or improved
- [ ] Code is more maintainable
- [ ] Follows project conventions
```
---
## Documentation Template
```markdown
## Documentation: [What's Being Documented]
### Summary
[What documentation is being added/updated and why]
### Changes Made
- [ ] Added new documentation
- [ ] Updated existing documentation
- [ ] Fixed errors/typos
- [ ] Added examples
- [ ] Improved clarity
- [ ] Added diagrams/screenshots
**Files Changed:**
- `docs/path/to/file.md` - [What changed]
### Type of Documentation
- [ ] Tutorial (learning-oriented)
- [ ] How-to guide (task-oriented)
- [ ] Reference (information-oriented)
- [ ] Explanation (understanding-oriented)
- [ ] API documentation
- [ ] README update
- [ ] Code comments
- [ ] Changelog entry
### Verification
- [ ] Technically accurate
- [ ] Examples work as shown
- [ ] Links are valid
- [ ] Proper formatting
- [ ] No spelling/grammar errors
- [ ] Appropriate level of detail
- [ ] Clear and understandable
### Screenshots/Examples
[If applicable, show before/after or provide visual examples]
### Related Issue
Fixes #[issue-number]
### Checklist
- [ ] Documentation is accurate
- [ ] Examples are tested
- [ ] No broken links
- [ ] Follows project documentation style
- [ ] Appropriate level of detail for audience
```
---
## Performance Improvement Template
```markdown
## Performance: [What's Being Optimized]
### Problem
**Current Performance:**
- Metric: [e.g., response time, memory usage]
- Measurement: [specific numbers]
- Impact: [who/what is affected]
**Bottleneck:**
[What's causing the performance issue]
### Solution
[Describe optimization approach]
**Why This Approach:**
[Rationale for chosen optimization]
### Changes Made
- `path/to/file.ext` - [Specific optimization]
**Algorithm Change:**
- Before: [O(n²), etc.]
- After: [O(n), etc.]
### Performance Impact
**Benchmarks:**
| Scenario | Before | After | Improvement |
|----------|--------|-------|-------------|
| Small | 10ms | 5ms | 50% faster |
| Medium | 100ms | 20ms | 80% faster |
| Large | 1000ms | 50ms | 95% faster |
**Methodology:**
[How benchmarks were measured]
### Tradeoffs
**Pros:**
- [Benefit 1]
- [Benefit 2]
**Cons:**
- [Tradeoff 1: e.g., slightly more memory usage]
- [Tradeoff 2: e.g., increased code complexity]
**Acceptable Because:**
[Why tradeoffs are acceptable]
### Testing
- [ ] Performance benchmarks included
- [ ] Existing tests pass
- [ ] No regressions in other areas
- [ ] Works under various load conditions
### Related Issue
Fixes #[issue-number]
### Checklist
- [ ] Performance improvement verified
- [ ] No correctness regressions
- [ ] Tradeoffs are acceptable
- [ ] Benchmarks included
- [ ] Works under various conditions
```
---
## Breaking Change Template
```markdown
## Breaking Change: [What's Changing]
### ⚠️ Breaking Change Warning
This PR introduces breaking changes. Requires version bump and migration guide.
### What's Breaking
[Clear description of what's changing and what breaks]
**Affected:**
- [API/function/behavior that's changing]
- [Versions affected]
- [Who needs to update]
### Why This Change
[Strong justification for breaking change]
**Problems with Current Approach:**
- [Problem 1]
- [Problem 2]
**Benefits of New Approach:**
- [Benefit 1]
- [Benefit 2]
### Changes Made
**API Changes:**
```[language]
// Before
oldFunction(param1, param2)
// After
newFunction({ param1, param2, newOption })
```
**Behavior Changes:**
- [What behaved differently before]
- [How it behaves now]
### Migration Guide
**For Users on v[X.Y.Z]:**
1. **Update Function Calls**
```[language]
// Old way
doSomething(a, b)
// New way
doSomething({ a, b })
```
2. **Update Configuration**
```[language]
// Old config
{ option: value }
// New config
{ newOption: value }
```
3. **Test Your Code**
[Specific things to test]
**Automated Migration:**
[If migration script provided]
```bash
npm run migrate
```
### Deprecation Period (if applicable)
- [ ] Old API marked as deprecated in v[X.Y.Z]
- [ ] Migration guide published
- [ ] Deprecation warnings added
- [ ] Removal scheduled for v[X.Y.Z]
### Testing
- [ ] New API tested
- [ ] Old behavior removed/deprecated
- [ ] Migration tested
- [ ] Documentation updated
### Related Issue
Implements #[issue-number]
### Checklist
- [ ] Breaking changes clearly documented
- [ ] Migration guide provided
- [ ] Strong justification provided
- [ ] Version bump appropriate (major version)
- [ ] Deprecation period considered
- [ ] Affected users notified (if possible)
```
---
## Small/Trivial Change Template
```markdown
## [Type]: [Brief Description]
### Changes
[One-line description of change]
### Type
- [ ] Typo fix
- [ ] Formatting
- [ ] Comment improvement
- [ ] Dead code removal
- [ ] Dependency update (patch)
- [ ] Config update
- [ ] Other trivial change
### Verification
- [ ] No functional changes
- [ ] Tests still pass (if applicable)
[Optional: If this fixes an issue]
Fixes #[issue-number]
```
---
## Test Addition Template
```markdown
## Tests: [What's Being Tested]
### Motivation
**Coverage Gap:**
[What wasn't covered before]
**Why Now:**
[Why adding these tests]
### Tests Added
**File:** `path/to/test/file.ext`
**Test Cases:**
- [ ] Happy path: [description]
- [ ] Edge case: [specific case]
- [ ] Edge case: [specific case]
- [ ] Error handling: [specific error]
**Coverage Improvement:**
- Before: [X%]
- After: [Y%]
- Increase: [+Z%]
### Testing
- [ ] All new tests pass
- [ ] Existing tests still pass
- [ ] Tests are meaningful (not just for coverage)
- [ ] Tests are maintainable
### Related Issue
Addresses #[issue-number]
### Checklist
- [ ] Tests cover the intended scenarios
- [ ] Tests are clear and readable
- [ ] Tests follow project conventions
- [ ] Coverage improved
```
---
## Security Fix Template
```markdown
## Security Fix: [Brief Description]
### ⚠️ Security Issue
[Describe vulnerability - be cautious about details if not yet disclosed]
**Severity:** [Critical/High/Medium/Low]
**CVSS Score:** [If applicable]
### Vulnerability Details
**Affected Versions:** [version range]
**Attack Vector:** [How it can be exploited]
**Impact:** [What attacker can do]
### Fix
[Describe how the fix addresses the vulnerability]
**Changes:**
- [Specific security improvement]
### Verification
- [ ] Exploit no longer works
- [ ] Security test added
- [ ] Similar code audited
- [ ] No new vulnerabilities introduced
### CVE
[CVE number if assigned, or "Pending" or "N/A"]
### Related Issue
Fixes #[issue-number] (if public)
[Or use private security advisory]
### Checklist
- [ ] Vulnerability fixed
- [ ] Security test added
- [ ] Similar code checked
- [ ] Changelog entry prepared (for after disclosure)
- [ ] Security advisory drafted (if needed)
```
---
## Dependency Update Template
```markdown
## Dependency Update: [Package Name]
### Update Details
**Package:** [package-name]
**From:** v[X.Y.Z]
**To:** v[A.B.C]
**Type:**
- [ ] Patch (bug fixes)
- [ ] Minor (new features, backwards compatible)
- [ ] Major (breaking changes)
### Motivation
- [ ] Security vulnerability fix
- [ ] Bug fixes
- [ ] New features needed
- [ ] Maintenance/housekeeping
- [ ] Performance improvements
**Specific Reason:**
[Why updating now]
### Changes Required
- [ ] No code changes needed
- [ ] Updated usage due to API changes
- [ ] Updated configuration
- [ ] Updated tests
- [ ] Updated documentation
**Code Changes:**
[If any, describe what changed]
### Breaking Changes
[List any breaking changes from changelog]
[How they were addressed]
### Testing
- [ ] All tests pass
- [ ] Manual testing completed
- [ ] No regressions
- [ ] New features work (if using them)
### Changelog Review
**Key changes from dependency:**
- [Change 1]
- [Change 2]
**Full changelog:** [link]
### Related Issue
Addresses #[issue-number]
### Checklist
- [ ] Dependency updated
- [ ] Code adapted to changes (if needed)
- [ ] Tests pass
- [ ] No security vulnerabilities
- [ ] Documentation updated (if needed)
```
---
## Choosing the Right Template
1. **Identify change type** - What kind of change is this?
2. **Select template** - Use the matching template
3. **Adapt to project** - Modify for project-specific requirements
4. **Fill completely** - Don't skip sections
5. **Add context** - Provide all relevant information
6. **Be clear** - Make reviewer's job easy
**Template Priority:**
1. Use project's template if exists
2. Adapt from these templates
3. Look at recent merged PRs for format
**Remember:** The goal is clear communication, not bureaucracy. Adapt templates to fit the situation.

851
skills/documentation-pr/SKILL.md Normal file
View File

@@ -0,0 +1,851 @@
---
name: oss:documentation-pr
description: Phase 4 of OSS contribution - Document changes and create a comprehensive, reviewable pull request. Writes clear PR description, documents code changes, creates changelog entries, and prepares for review. Use when implementation is complete and ready to submit work.
---
# Phase 4: Documentation & PR Creation
Document changes and create a comprehensive, reviewable pull request.
## Purpose
Create a pull request that:
- Clearly communicates changes
- Justifies the approach
- Makes reviewer's job easy
- Increases merge probability
- Serves as documentation
## When to Use
**Triggers:**
- "PR 작성"
- "pull request 준비"
- "문서화해줘"
- "리뷰 준비"
**Use when:**
- Implementation is complete
- Tests pass locally
- Ready to submit work
- Want to create high-quality PR
## PR Creation Framework
### Step 0: CONTRIBUTING.md Final Verification
**MANDATORY: Final compliance check before PR submission**
- Review CONTRIBUTING.md requirements from Phase 1 one last time
- Verify ALL requirements are met:
- Code style and formatting standards
- Commit message format and conventions
- Branch naming requirements
- Testing requirements
- Documentation standards
- PR submission process
- **PR MUST strictly follow all CONTRIBUTING.md guidelines**
### Step 1: Pre-PR Checklist
Verify everything is ready before creating PR.
```markdown
### Pre-PR Checklist
**CONTRIBUTING.md Compliance:**
- [ ] All contribution guidelines followed
- [ ] Commit messages follow required format
- [ ] Branch named according to conventions
- [ ] Code style matches project standards
**Code quality:**
- [ ] All tests pass locally
- [ ] Linting passes
- [ ] Type checking passes (if applicable)
- [ ] Build succeeds
- [ ] No compiler warnings
**Functionality:**
- [ ] All requirements implemented
- [ ] Edge cases handled
- [ ] Error handling complete
- [ ] Manual testing done
**Tests:**
- [ ] New tests added
- [ ] Existing tests still pass
- [ ] Coverage meets threshold
- [ ] Tests are meaningful
**Documentation:**
- [ ] Code comments added where needed
- [ ] README updated (if needed)
- [ ] CHANGELOG entry added
- [ ] API docs updated (if applicable)
**Git hygiene:**
- [ ] Branch is up to date with main
- [ ] Commits are logical and focused
- [ ] Commit messages are clear
- [ ] No merge commits (rebased if needed)
- [ ] No secrets or sensitive data
**Review readiness:**
- [ ] Self-reviewed all changes
- [ ] Removed debugging code
- [ ] Removed commented-out code
- [ ] No unrelated changes
```
### Step 2: Branch Management
Ensure clean branch state.
**Branch best practices:**
**IMPORTANT: Follow CONTRIBUTING.md branch naming conventions**
```bash
# Create feature branch following project conventions
# Check CONTRIBUTING.md for required format (e.g., feature/, fix/, etc.)
git checkout -b feature/issue-123-description
# Update from main
git fetch origin
git rebase origin/main
# Check status
git status
# Should be clean, ahead of main
# View your commits
git log origin/main..HEAD --oneline
# Should be focused, logical commits
# If commits need cleanup, interactive rebase
git rebase -i origin/main
# Squash, reword, reorder as needed
```
**Commit message quality:**
**IMPORTANT: Follow CONTRIBUTING.md commit message format**
- Check project's required commit message convention
- Some projects use Conventional Commits, others have custom formats
- Verify before writing commit messages
```markdown
### Good Commit Messages
**Format (verify with CONTRIBUTING.md):**
```
type(scope): brief description
Detailed explanation of what and why (not how).
Focus on the motivation and context.
Closes #123
```
**Types:**
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Formatting, no code change
- refactor: Code change without behavior change
- test: Adding tests
- chore: Build process, tooling
**Examples:**
✅ **Good:**
```
fix(auth): handle null user in session validation
Previously, the session validator crashed when user
was null during logout race conditions. Now returns
early with invalid session.
Closes #123
```
❌ **Bad:**
```
fix stuff
```
✅ **Good:**
```
feat(export): add CSV export functionality
Implements CSV export with customizable columns and
optional header row. Uses streaming for large datasets
to avoid memory issues.
- Add exportToCSV function
- Add column selection UI
- Add tests for edge cases
Closes #456
```
❌ **Bad:**
```
added feature
```
```
### Step 3: PR Title
Craft clear, descriptive PR title.
**Title format:**
```markdown
### PR Title
**Format:** [Type] Brief description of change
**Examples:**
✅ Good titles:
- "Fix: Handle null values in session validation"
- "Feature: Add CSV export with column selection"
- "Refactor: Extract validation logic to separate module"
- "Docs: Add examples for authentication flow"
❌ Bad titles:
- "Fix bug"
- "Update code"
- "Changes"
- "PR for issue #123"
**Guidelines:**
- Start with type: Fix/Feature/Refactor/Docs
- Use imperative mood ("Add" not "Added")
- Be specific but concise
- Mention issue number if applicable
- Max ~60-70 characters
```
### Step 4: PR Description
Write comprehensive PR description.
**Description template:**
```markdown
## PR Description Template
### Summary
[2-3 sentences: What changes, why they're needed, what problem they solve]
### Changes Made
- [Change 1: specific, actionable description]
- [Change 2]
- [Change 3]
### Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement
- [ ] Test coverage improvement
### Related Issue
Fixes #[issue-number]
<!-- or -->
Relates to #[issue-number]
### How to Test
1. [Step 1: how to set up test scenario]
2. [Step 2: what to do]
3. [Step 3: what to verify]
**Expected behavior:** [what should happen]
### Screenshots (if applicable)
**Before:**
[screenshot or description]
**After:**
[screenshot or description]
### Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published
### Additional Notes
[Any context, tradeoffs, alternative approaches considered, future work, or breaking changes]
```
**Customized example:**
```markdown
## Add CSV Export Functionality
### Summary
Implements CSV export feature requested in #456. Users can now export data
tables to CSV format with customizable column selection and optional headers.
Uses streaming approach to handle large datasets without memory issues.
### Changes Made
- Add `exportToCSV` function in `utils/export.js`
- Add column selection checkbox UI in export dialog
- Add "Include Headers" toggle option
- Implement streaming for datasets >10k rows
- Add comprehensive tests for edge cases (empty data, special characters, large datasets)
- Update README with export feature documentation
### Type of Change
- [x] New feature (non-breaking change which adds functionality)
### Related Issue
Fixes #456
### How to Test
1. Navigate to any data table page
2. Click "Export" button in toolbar
3. Select columns to export using checkboxes
4. Toggle "Include Headers" option
5. Click "Download CSV"
6. Verify downloaded file contains expected data
**Expected behavior:** CSV file downloads with selected columns, properly escaped special characters, and headers if enabled.
**Edge cases to test:**
- Empty dataset → Downloads empty file or shows warning
- Large dataset (>10k rows) → Progress indicator shows, no memory issues
- Special characters in data → Properly escaped in CSV
### Screenshots
**Export Dialog:**
[screenshot of new export UI]
**Sample Output:**
```csv
Name,Email,Role
John Doe,john@example.com,Admin
Jane Smith,jane@example.com,User
```
### Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published
### Additional Notes
**Design decisions:**
- Used streaming for large datasets instead of loading all in memory
- Followed RFC 4180 for CSV format to ensure compatibility
- Made column selection persistent in localStorage
**Future improvements (out of scope for this PR):**
- Add Excel export format
- Add export templates
- Add scheduled exports
**Breaking changes:** None
```
### Step 5: Project-Specific PR Templates
Adapt to project's PR template if exists.
**Check for templates:**
```bash
# Look for PR template
cat .github/PULL_REQUEST_TEMPLATE.md
cat .github/pull_request_template.md
cat docs/pull_request_template.md
# Some projects use issue templates
ls .github/ISSUE_TEMPLATE/
```
**Follow template exactly:**
- Don't skip sections
- Fill in all required fields
- Check all relevant boxes
- Provide requested information
**If no template:**
- Use framework's template above
- Look at recent merged PRs for format
- Follow community conventions
### Step 6: Review Preparation
Make reviewer's job easy.
**Reviewer-friendly practices:**
```markdown
### Making PR Easy to Review
**Size:**
- 🟢 Small: < 200 lines changed
- 🟡 Medium: 200-500 lines
- 🔴 Large: > 500 lines (consider splitting)
**If PR is large:**
- Explain why it can't be split
- Provide roadmap of changes
- Highlight key areas to review
- Offer to review in parts
**Structure:**
- Logical commit history
- Each commit compiles/works
- Related changes grouped
- Unrelated changes separated
**Communication:**
- Clear descriptions
- Inline comments on tricky code
- Link to design docs
- Explain tradeoffs
**Context:**
- Why this approach?
- What alternatives considered?
- Any performance implications?
- Breaking changes?
```
**Add code comments in PR:**
Use GitHub's review comment feature to explain:
- Why specific approach taken
- Known limitations
- Areas you want feedback on
- Anything non-obvious
**Example:**
```javascript
// (Add PR comment: "This uses binary search instead of linear scan
// because dataset can be large. Benchmarked 100x faster on 10k items.")
const index = binarySearch(array, target)
```
### Step 7: CI/CD Preparation
Ensure automated checks will pass.
```markdown
### CI/CD Checklist
**Before pushing:**
- [ ] All tests pass locally
- [ ] Linting passes
- [ ] Type checking passes
- [ ] Build succeeds
- [ ] Coverage meets threshold
**After pushing:**
- [ ] Monitor CI/CD pipeline
- [ ] All checks pass
- [ ] No flaky test failures
- [ ] Build artifacts generated (if applicable)
**If CI fails:**
- Fix immediately
- Don't wait for reviewer
- Force push if fixing commits
- Comment explaining fixes
```
**Common CI failures:**
```markdown
### Troubleshooting CI
**Tests fail in CI but pass locally:**
- [ ] Check for timezone assumptions
- [ ] Check for file path assumptions (Windows vs Unix)
- [ ] Check for race conditions
- [ ] Check for missing test data
- [ ] Check for environment differences
**Linting fails:**
```bash
# Run same linter locally
npm run lint
# Auto-fix if possible
npm run lint:fix
```
**Build fails:**
```bash
# Clean build locally
rm -rf node_modules dist
npm install
npm run build
```
**Coverage below threshold:**
```bash
# Check coverage locally
npm run test:coverage
# Add missing tests
```
```
### Step 8: PR Submission
Submit PR and engage with feedback.
**Submission process:**
```bash
# Push branch to remote
git push -u origin feature/issue-123-description
# Create PR via CLI (if using gh)
gh pr create --title "Fix: Handle null user in session" \
--body-file pr-description.md \
--label bug \
--assignee @me
# Or via GitHub web interface
# 1. Go to repository
# 2. Click "Pull requests" tab
# 3. Click "New pull request"
# 4. Select your branch
# 5. Fill in title and description
# 6. Click "Create pull request"
```
**After submission:**
```markdown
### Post-Submission Actions
**Immediately:**
- [ ] Comment on original issue linking to PR
"Submitted PR #789 to address this issue"
- [ ] Add appropriate labels (if permissions allow)
- [ ] Request review from maintainers (if process requires)
- [ ] Link any related issues/PRs
**Monitor:**
- [ ] CI/CD status - fix if failing
- [ ] Review comments - respond promptly
- [ ] Merge conflicts - resolve quickly
- [ ] Feedback - address constructively
**Be responsive:**
- Respond to comments within 24-48 hours
- Thank reviewers for feedback
- Explain reasoning if disagreeing
- Make requested changes promptly
- Keep discussion respectful and professional
```
### Step 9: Handling Feedback
Respond to review comments effectively.
**Review response best practices:**
```markdown
### Responding to Reviews
**Good practices:**
✅ **Acknowledge feedback:**
"Good catch! I'll fix this."
"That's a great point. Let me refactor this."
✅ **Explain reasoning:**
"I used approach X because Y. However, I see your point about Z. Let me try W instead."
✅ **Ask clarifying questions:**
"I'm not sure I understand the concern here. Could you elaborate on the edge case you're thinking of?"
✅ **Suggest alternatives:**
"Would you prefer approach A or B? I think A is simpler but B is more extensible."
✅ **Mark resolved:**
After addressing comment, reply "Done" or "Fixed in [commit]" and resolve thread
❌ **Avoid:**
- Defensive responses
- Ignoring feedback
- Taking criticism personally
- Arguing unnecessarily
- Making excuses
**Types of feedback:**
**1. Bugs/Issues (Must fix):**
- Fix immediately
- Add test to prevent regression
- Thank reviewer
**2. Style/Convention (Must fix):**
- Follow project standards
- Even if you disagree
- Consistency matters
**3. Suggestions (Evaluate):**
- Consider merit
- Discuss tradeoffs
- Implement if better
- Explain if not
**4. Questions (Answer):**
- Clarify approach
- Add comments if unclear
- May indicate code needs simplification
**5. Nitpicks (Optional):**
- Fix if easy
- Push back if not valuable
- "Will fix in follow-up" if time-consuming
```
**Making changes:**
```bash
# Make requested changes
[edit files]
# Commit changes
git add [files]
git commit -m "Address review feedback: improve error handling"
# Push to PR
git push
# Comment on review
"Changes made in [commit-hash]"
```
### Step 10: Merge Preparation
Final steps before merge.
```markdown
### Pre-Merge Checklist
**Code review:**
- [ ] All reviewer comments addressed
- [ ] Requested changes made
- [ ] Approvals received (per project policy)
- [ ] No unresolved threads
**CI/CD:**
- [ ] All checks passing
- [ ] No merge conflicts
- [ ] Branch up to date with main
**Final review:**
- [ ] Re-review your changes
- [ ] Check for any last-minute issues
- [ ] Verify all commits are squashed (if project requires)
- [ ] Verify commit message is clean
**Documentation:**
- [ ] CHANGELOG updated
- [ ] README current
- [ ] Migration guide (if breaking)
- [ ] Release notes drafted (if applicable)
**Ready to merge:**
- [ ] Maintainer approval received
- [ ] All checks passed
- [ ] No outstanding concerns
- [ ] Follow-up issues created (if any)
```
## PR Quality Checklist
Use this to ensure high-quality PRs:
```markdown
### PR Quality Checklist
**Clarity:**
- [ ] Title is clear and descriptive
- [ ] Description explains what and why
- [ ] Changes are well-organized
- [ ] Context is provided
**Completeness:**
- [ ] All requirements addressed
- [ ] Tests included
- [ ] Documentation updated
- [ ] Edge cases handled
**Reviewability:**
- [ ] PR is focused (single concern)
- [ ] Size is reasonable
- [ ] Commits are logical
- [ ] Code is self-explanatory
**Technical:**
- [ ] Follows conventions
- [ ] No obvious issues
- [ ] Tests pass
- [ ] CI passes
**Communication:**
- [ ] Original issue linked
- [ ] How to test explained
- [ ] Tradeoffs documented
- [ ] Breaking changes highlighted
```
## Common Pitfalls
**Avoid:**
❌ **Vague descriptions** - "Fixed bug" tells nothing
❌ **Huge PRs** - Hard to review, less likely to merge
❌ **Mixing concerns** - Multiple unrelated changes
❌ **No tests** - Reviewers will ask for them
❌ **Ignoring CI failures** - Shows lack of diligence
❌ **Poor commit messages** - Makes history useless
❌ **Defensive attitude** - Makes collaboration difficult
❌ **Rushing** - Quality beats speed
## Output Format
Provide PR creation guide:
```markdown
# 📤 Pull Request Ready: [Issue Title]
**Issue:** #[number]
**Branch:** [branch-name]
**Status:** Ready to submit
---
## PR Information
**Title:**
```
[Type]: [Clear description]
```
**Description:**
```
[Full PR description using template]
```
**Labels:** [suggested labels]
---
## Pre-Submission Checklist
**Code:**
- ✅ Tests pass
- ✅ Linting passes
- ✅ Build succeeds
- ✅ Self-reviewed
**Documentation:**
- ✅ Comments added
- ✅ README updated
- ✅ CHANGELOG entry
- ✅ API docs updated
**Git:**
- ✅ Branch up to date
- ✅ Commits clean
- ✅ No secrets
- ✅ No merge commits
---
## Submission Command
```bash
# Push branch
git push -u origin [branch-name]
# Create PR (via gh CLI)
gh pr create --title "[title]" --body "[description]"
# Or use GitHub web interface
# https://github.com/[owner]/[repo]/compare/[branch]
```
---
## Post-Submission
**Next steps:**
1. Monitor CI/CD pipeline
2. Respond to review comments promptly
3. Address feedback constructively
4. Keep PR updated with main branch
**Timeline:**
- Review typically within: [project-specific]
- Address feedback within: 24-48 hours
- Merge after: approvals + CI pass
---
## 🎉 Contribution Complete!
Thank you for contributing to open source!
**After merge:**
- [ ] Close related issues
- [ ] Update local main branch
- [ ] Delete feature branch
- [ ] Celebrate! 🎉
**Future contributions:**
- Consider more complex issues
- Help review others' PRs
- Improve documentation
- Engage with community
```
## Integration with Main Framework
When invoked from main framework:
1. **Receive context:** Implemented changes from Phase 3, test results, branch state
2. **Guide documentation:** PR title, description, checklist
3. **Verify readiness:** All quality checks met
4. **Return PR content:** Ready to copy/paste or submit
5. **Update tracker:** Mark Phase 4 complete - contribution done!
This completes the full OSS contribution workflow.
## Learning from Reviews
**Track feedback patterns:**
- What do reviewers commonly ask for?
- What mistakes do you repeat?
- What can you catch in self-review?
- How to improve next PR?
**Build reputation:**
- High-quality PRs
- Responsive to feedback
- Respectful communication
- Consistent contributions
**Each PR is practice for the next one!**

822
skills/issue-analysis/SKILL.md Normal file
View File

@@ -0,0 +1,822 @@
---
name: oss:issue-analysis
description: Phase 2 of OSS contribution - Deep analysis combining issue requirements with codebase exploration. Extracts requirements, explores code structure, identifies exact code locations to fix, traces execution paths, and maps code-level changes needed. Use when starting work on selected issue.
---
# Phase 2: Issue Analysis & Code Exploration
Deep analysis of issue requirements combined with codebase exploration to identify exact code changes needed.
## Purpose
Transform an issue into actionable code-level understanding by:
- **Understanding requirements:** What needs to be done and why
- **Exploring codebase:** Project structure, conventions, patterns
- **Locating code:** Find exact files/functions to modify
- **Identifying problems:** Pinpoint broken/missing code
- **Planning changes:** Map requirements to specific code modifications
## When to Use
**Triggers:**
- "이 이슈 분석해줘"
- "코드에서 어디를 고쳐야 하나?"
- "이슈와 코드 연결"
- "문제 있는 코드 찾기"
**Use when:**
- Starting work on a selected issue
- Need to understand both requirements AND code
- Want to identify exact modification points
- Ready to plan implementation
## Integrated Analysis Framework
### Step 0: Review CONTRIBUTING.md Requirements
**MANDATORY: Before analyzing the issue, review project contribution guidelines**
- Refer to CONTRIBUTING.md read in Phase 1
- Ensure your analysis aligns with project conventions
- Note any specific requirements for:
- Code style and formatting
- Testing requirements
- Documentation standards
- Commit message format
- Branch naming conventions
**All analysis and subsequent work MUST comply with these guidelines**
### Step 1: Issue Type & Requirements Extraction
Identify issue type and extract core requirements.
**Issue Types:**
**Bug Fix:**
```markdown
### Bug Analysis Template
**Current Behavior:**
[What actually happens - be specific]
**Expected Behavior:**
[What should happen - reference docs/specs]
**Reproduction Steps:**
1. [Step 1]
2. [Step 2]
3. [Observe: ...]
**Environment:**
- Version: [version]
- Platform: [OS/browser/etc]
**Impact:**
- Severity: [Critical/High/Medium/Low]
- Affected users: [who/how many]
```
**Feature Request:**
```markdown
### Feature Analysis Template
**User Story:**
As a [user type], I want [capability] so that [benefit].
**Functional Requirements:**
1. [Requirement 1 - must have]
2. [Requirement 2 - must have]
3. [Requirement 3 - nice to have]
**Acceptance Criteria:**
- [ ] [Criterion 1 - specific and testable]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
```
**Refactoring:**
```markdown
### Refactoring Analysis Template
**Current Problems:**
1. [Problem 1: e.g., duplicated code across X files]
2. [Problem 2: e.g., poor separation of concerns]
**Desired Outcome:**
[What the code should look like after refactoring]
**Constraints:**
- [ ] No behavior changes
- [ ] All existing tests must pass
- [ ] No API changes (if library)
```
### Step 2: Project Structure & Convention Understanding
Explore codebase to understand organization and conventions.
**A. Directory Structure Mapping:**
```bash
# Get project overview
tree -L 2 -d
# Identify key directories
ls -la
```
```markdown
### Project Structure
**Main source:** [path to primary code]
**Key directories:**
- `src/` or `lib/` - Main source code
- `tests/` or `__tests__/` - Test files
- `docs/` - Documentation
- `.github/` - CI/CD, workflows
**Organization principle:**
- [x] By feature (e.g., /users, /products)
- [ ] By layer (e.g., /models, /views, /controllers)
- [ ] By type (e.g., /components, /utils, /services)
**Technologies:**
- Language: [language + version]
- Framework: [framework]
- Build tool: [npm/cargo/maven/etc]
- Testing: [jest/pytest/etc]
```
**B. Code Conventions Discovery:**
```bash
# Check for style configs
cat .prettierrc .eslintrc package.json
# Find naming patterns
find src -type f -name "*.js" | head -10
```
```markdown
### Code Conventions
**File Naming:**
- Components: [e.g., PascalCase.tsx]
- Utilities: [e.g., camelCase.ts]
- Tests: [e.g., file.test.js or file_test.go]
**Code Style:**
- Indentation: [2 spaces / 4 spaces / tabs]
- Quotes: [single / double]
- Import order: [external, internal, relative]
**Naming Patterns:**
- Classes: [PascalCase]
- Functions: [camelCase / snake_case]
- Constants: [UPPER_SNAKE_CASE]
```
**C. Testing Patterns:**
```bash
# Find test locations
find . -name "*test*" -type f | head -5
# Check test framework
cat package.json | grep -A5 "scripts"
```
```markdown
### Testing Strategy
**Test Location:**
- Unit tests: [e.g., __tests__/, alongside source]
- Integration tests: [location]
**Test Framework:** [Jest / pytest / go test / etc]
**Test Naming Pattern:**
- [describe/test, test_, Test*]
**Run Commands:**
```bash
npm test # All tests
npm test -- file.test.js # Specific test
npm test -- --coverage # With coverage
```
```
### Step 3: Code Location Discovery
Find exact files and functions related to the issue.
**A. Entry Point Discovery:**
```bash
# For UI bugs/features - find component
rg "ComponentName" --type tsx
rg "class.*ComponentName"
# For API/backend - find endpoint
rg "app\.(get|post|put).*endpoint"
rg "@app.route|router"
# For CLI - find command
rg "subcommand|command.*name"
# For library - find exported function
rg "export (function|class|const).*functionName"
```
```markdown
### Entry Points
**Primary entry point:**
- File: `src/components/UserProfile.tsx:45`
- Function/Component: `UserProfile`
- Purpose: [what this code does]
**How to trigger:**
[Steps to reach this code - e.g., click button, call API]
```
**B. Find Similar/Related Code:**
```bash
# Find similar features for reference
rg "similar-feature" --type js
# Find similar patterns
find . -name "*Similar*.js"
# Find related tests
rg "describe.*YourFeature" tests/
```
```markdown
### Reference Examples
**Similar code to reference:**
1. `src/components/UserSettings.tsx:120`
- Similar pattern for form handling
- Shows validation approach
2. `src/utils/validation.ts:45`
- Input validation logic
- Error handling pattern
```
### Step 4: Code-Level Problem Identification
**THIS IS THE CRITICAL STEP - Find exact code that needs fixing**
**A. For Bug Fixes - Trace to Root Cause:**
```bash
# Search for error message or symptom
rg "error message text"
# Find function definitions
rg "function buggyFunction|def buggy_function"
# Find all callers
rg "buggyFunction\("
```
```markdown
### Bug Root Cause Analysis
**Symptom Location:**
- File: `src/auth/session.ts:78`
- Function: `validateSession`
- Problem: Crashes when `user` is null
**Code Analysis:**
```typescript
// CURRENT CODE (BROKEN)
function validateSession(sessionId: string) {
const session = getSession(sessionId)
return session.user.id // ❌ CRASHES if user is null
}
```
**Root Cause:**
- Missing null check for `session.user`
- Happens during logout race condition
**Needs to be changed to:**
```typescript
// FIXED CODE
function validateSession(sessionId: string) {
const session = getSession(sessionId)
if (!session?.user) { // ✅ Add null check
return null
}
return session.user.id
}
```
**Additional locations to check:**
- [ ] `src/auth/logout.ts:34` - may have similar issue
- [ ] `src/auth/session.test.ts` - add test for null user
```
**B. For Features - Identify Where to Add Code:**
```bash
# Find where similar features are implemented
rg "similar feature" --type js
# Find integration points
rg "import.*Component|from.*module"
```
```markdown
### Feature Implementation Points
**Where to add code:**
**1. New function needed:**
- Location: `src/utils/export.ts` (new file)
- Function: `exportToCSV(data, options)`
- Based on: `src/utils/exportToJSON.ts` (similar pattern)
**2. UI Integration:**
- File: `src/components/DataTable.tsx:120`
- Add: Export button in toolbar
- Pattern: Follow existing "Download" button at line 115
**3. Hook into existing flow:**
- File: `src/components/DataTable.tsx:45`
- Add: Import new export function
- Call: On button click handler
**Code to add:**
```typescript
// In DataTable.tsx
import { exportToCSV } from '@/utils/export'
// Around line 120, add:
<Button onClick={() => exportToCSV(data, { headers: true })}>
Export CSV
</Button>
```
```
**C. For Refactoring - Map Code Smells:**
```bash
# Find duplicated code
rg -A10 "duplicated pattern"
# Find long functions
# (Manual inspection)
```
```markdown
### Refactoring Map
**Code smells identified:**
**1. Duplicated validation logic:**
- `src/auth/login.ts:34-50` (17 lines)
- `src/auth/register.ts:28-44` (17 lines)
- `src/auth/resetPassword.ts:15-31` (17 lines)
**Solution:**
- Extract to: `src/auth/validators.ts`
- New function: `validateUserInput(input)`
- Replace 3 duplications with function call
**2. God function:**
- `src/api/userController.ts:100-350` (250 lines!)
- Does: validation + business logic + DB + response
**Solution:**
- Split into:
- `validateUserData()` at line 100
- `createUser()` at line 150
- `sendWelcomeEmail()` at line 200
```
### Step 5: Execution Path Tracing
Trace code flow to understand full context.
```markdown
### Execution Flow
**For [bug/feature]: [description]**
```
1. Entry: src/components/Login.tsx:89 - handleSubmit()
└─> Calls: validateCredentials(username, password)
2. Flow: src/auth/validation.ts:23 - validateCredentials()
└─> Calls: checkPassword(password)
└─> Returns: {valid: boolean, error?: string}
3. Bug: src/auth/validation.ts:45 - checkPassword()
└─> ❌ PROBLEM: Doesn't handle null password
└─> FIX: Add null check at line 46
4. Result: Returns to handleSubmit, shows error
```
**Key functions in flow:**
- `handleSubmit()` @ Login.tsx:89 - Form submission
- `validateCredentials()` @ validation.ts:23 - Main validator
- `checkPassword()` @ validation.ts:45 - ❌ NEEDS FIX HERE
**Data transformations:**
- Input: `{username: string, password: string}`
- Validation: checks format, length, special chars
- Output: `{valid: boolean, error?: string}`
```
### Step 6: Dependency & Impact Analysis
Understand what depends on your changes.
```bash
# Find all callers
rg "functionName\("
# Find all imports
rg "import.*ModuleName"
# Find test coverage
rg "describe.*functionName" tests/
```
```markdown
### Dependencies & Impact
**Upstream (what calls this code):**
- `src/components/Login.tsx:89` - Login form
- `src/components/Register.tsx:67` - Registration form
- `src/api/authController.ts:120` - API endpoint
**Impact of change:**
- 🟢 Low risk - adding validation only
- All callers already handle error case
- Existing tests cover error path
**Downstream (what this calls):**
- `src/utils/crypto.ts:hashPassword()` - crypto library
- `src/models/User.ts:findByUsername()` - DB query
**Side effects:**
- None - pure validation function
- No state mutations
- No external calls
**Test coverage:**
- Current: `tests/auth/validation.test.ts`
- Need to add: test case for null password
```
### Step 7: Modification Plan
Create concrete plan of what code to change.
```markdown
### Modification Plan
**Files to modify:**
**1. PRIMARY FIX: src/auth/validation.ts**
- **Line 45-50:** Function `checkPassword()`
- **Change type:** Add null/undefined check
- **Before:**
```typescript
function checkPassword(password: string): boolean {
return password.length >= 8 // ❌ Crashes if null
}
```
- **After:**
```typescript
function checkPassword(password: string | null): boolean {
if (!password) { // ✅ Add null check
return false
}
return password.length >= 8
}
```
- **Risk:** 🟢 Low - defensive programming
**2. ADD TEST: tests/auth/validation.test.ts**
- **Line:** After line 67 (add new test case)
- **Add:**
```typescript
it('should return false for null password', () => {
expect(checkPassword(null)).toBe(false)
})
```
**3. UPDATE TYPES: src/types/auth.ts** (if needed)
- **Line 12:** Update PasswordInput type to allow null
**Files NOT to change:**
- ❌ `src/components/Login.tsx` - already handles errors correctly
- ❌ `src/api/authController.ts` - no changes needed
```
### Step 8: Edge Cases & Implicit Requirements
Identify edge cases from code analysis.
```markdown
### Edge Cases Discovered
**From code inspection:**
- [ ] Null password: `checkPassword(null)` - FOUND in code trace
- [ ] Empty string: `checkPassword("")` - check if handled
- [ ] Very long password: `checkPassword("x".repeat(10000))` - DOS risk?
- [ ] Unicode characters: `checkPassword("パスワード")` - supported?
- [ ] SQL injection: `checkPassword("' OR 1=1--")` - sanitized?
**Integration concerns:**
- Depends on: crypto library (trusted)
- Affects: Login, Register, Reset Password flows
- Breaking change: No - only adding validation
**Performance:**
- No loops or heavy computation
- O(1) complexity
- No performance concerns
**Security:**
- Input validation ✅
- No sensitive data logged
- Follow OWASP guidelines
```
### Step 9: Acceptance Criteria & Scope
Define concrete success criteria and scope.
```markdown
### Scope Definition
**In Scope:**
1. Add null check to `checkPassword()` function
2. Add unit test for null password case
3. Verify no crashes on null input
**Out of Scope:**
1. Password strength improvements (separate issue #456)
2. UI error message improvements (separate issue #457)
3. Refactoring validation.ts (not requested)
**Complexity:** 🟢 Simple (< 2 hours)
- Single function change
- One test case addition
- Low risk change
### Acceptance Criteria
**Functional:**
- [ ] `checkPassword(null)` returns `false` (no crash)
- [ ] `checkPassword(undefined)` returns `false` (no crash)
- [ ] `checkPassword("valid")` still works correctly
- [ ] Existing tests still pass
**Quality:**
- [ ] New test added and passing
- [ ] No linting errors
- [ ] Type definitions updated
- [ ] Code follows project conventions
**Verification:**
```bash
npm test # All tests pass
npm run lint # No errors
npm run type-check # No type errors
```
**Manual testing:**
1. Open login form
2. Submit with empty password
3. Verify: No crash, shows error message
```
## Analysis Patterns by Issue Type
### Bug Fix Pattern
1. **Understand symptom** - Read issue description
2. **Reproduce locally** - Follow reproduction steps
3. **Explore codebase** - Find project structure
4. **Locate bug** - Trace code to root cause
5. **Identify fix point** - Exact line to change
6. **Plan changes** - What code to modify
7. **Consider side effects** - Impact analysis
### Feature Pattern
1. **Understand need** - User story, use cases
2. **Explore codebase** - Structure and conventions
3. **Find similar features** - Reference implementations
4. **Identify integration points** - Where to add code
5. **Plan new code** - What to create
6. **Map dependencies** - What it will interact with
7. **Design interface** - API, props, parameters
### Refactoring Pattern
1. **Identify code smell** - What's wrong
2. **Explore codebase** - Understand context
3. **Map all instances** - Find all occurrences
4. **Plan extraction** - New structure
5. **Ensure test coverage** - Safety net
6. **Plan incremental steps** - Small safe changes
7. **Verify no behavior change** - Tests still pass
## Output Format
Provide comprehensive analysis with code-level details:
```markdown
# 🔍 Issue Analysis: [Issue Title]
**Issue:** #[number] | **Type:** [bug/feature/refactor]
**Status:** Ready to implement
---
## Summary
[2-3 sentences: what needs to be done, what code needs to change, why]
---
## Requirements
### Issue Requirements
[What user/maintainer wants]
### Code Requirements
[What code needs to change based on exploration]
---
## Project Understanding
### Structure
[Key directories and organization]
### Conventions
[Naming, style, patterns to follow]
### Testing
[Framework, location, how to run]
---
## Code Analysis
### Entry Points
- [File:line - function/component name]
### Problem Code Identified
**File: [path]**
**Line: [number]**
**Function: [name]**
**Current code (BROKEN):**
```language
[actual problematic code]
```
**Problem:**
- [what's wrong]
- [why it breaks]
**Fix needed:**
```language
[corrected code]
```
### Execution Flow
```
[trace from entry to problem]
```
---
## Modification Plan
### Files to Change
**1. [file path]**
- **Line:** [number]
- **Function:** [name]
- **Change:** [specific modification]
- **Before/After:** [code snippets]
**2. [test file]**
- **Add:** [new test cases]
### Impact Analysis
- **Upstream callers:** [list]
- **Risk:** 🟢/🟡/🔴
- **Breaking change:** Yes/No
---
## Testing Plan
**Existing tests to verify:**
- [test file:description]
**New tests to add:**
- [ ] Test case 1: [description]
- [ ] Test case 2: [description]
**Test commands:**
```bash
npm test
npm test -- specific.test.js
```
---
## Edge Cases
- [ ] [Edge case 1 - how to handle]
- [ ] [Edge case 2 - how to handle]
---
## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] All tests pass
- [ ] Follows CONTRIBUTING.md guidelines
---
## Implementation Checklist
- [ ] Fix code at [file:line]
- [ ] Add test at [test-file]
- [ ] Run tests - all pass
- [ ] Run linter - no errors
- [ ] Manual verification
---
## Next Steps
✅ Analysis complete - Ready for **Phase 3: Solution Implementation**
**Start with:**
1. [Specific first task - e.g., "Fix checkPassword() at validation.ts:45"]
2. [Second task]
3. [Third task]
```
## Integration with Main Framework
When invoked from main framework:
1. **Receive context:** Issue URL, type from Phase 1
2. **Execute integrated analysis:**
- Extract requirements
- Explore codebase structure
- Locate exact code to change
- Identify problems in code
- Plan modifications
3. **Return comprehensive analysis:** Ready to implement
4. **Update tracker:** Mark Phase 2 complete
5. **Transition:** Phase 3 (Implementation) with concrete code-level plan
## Common Pitfalls
**Avoid:**
❌ **Analyzing requirements without looking at code** - Will miss context
❌ **Exploring code without understanding requirements** - Will get lost
❌ **Assuming code structure** - Always verify by reading
❌ **Stopping at "what" without finding "where"** - Need exact locations
❌ **Ignoring existing patterns** - Must follow project conventions
❌ **Not tracing full execution path** - Will miss side effects
❌ **Forgetting to check tests** - Test changes are part of solution
## Verification Before Implementation
**Before moving to Phase 3, verify:**
- [ ] Requirements fully understood
- [ ] Codebase structure mapped
- [ ] Exact modification points identified
- [ ] Problem code located (for bugs)
- [ ] Integration points clear (for features)
- [ ] All duplications found (for refactoring)
- [ ] Execution path traced
- [ ] Dependencies identified
- [ ] Test strategy planned
- [ ] Edge cases listed
- [ ] Impact assessed and acceptable
If any unclear, dig deeper or ask maintainer.

340
skills/issue-discovery/SKILL.md Normal file
View File

@@ -0,0 +1,340 @@
---
name: oss:issue-discovery
description: Phase 1 of OSS contribution - Find and evaluate suitable issues matching your skills, time, and learning goals. Filters by labels, assesses project health, and provides structured recommendations. Use when starting OSS contribution, looking for beginner-friendly issues, or evaluating multiple issue options.
---
# Phase 1: Issue Discovery & Triage
Find and evaluate suitable issues to work on in open source projects.
## Purpose
Help contributors identify issues that match their:
- Skill level and experience
- Available time commitment
- Learning goals
- Interest areas
## When to Use
**Triggers:**
- "좋은 이슈 찾아줘"
- "beginner-friendly 이슈 추천"
- "이 프로젝트에서 뭘 할 수 있을까?"
- "이 이슈가 나한테 맞을까?"
**Use when:**
- Starting contribution to a new project
- Looking for next issue after completing one
- Evaluating multiple issue options
- Unsure which issue to tackle
## Discovery Process
### Step 1: Understand Contributor Profile
Ask or infer:
- **Experience level:** First-time, intermediate, experienced
- **Tech stack familiarity:** Languages, frameworks, tools
- **Time availability:** Quick fix, moderate, substantial project
- **Goals:** Learn, build portfolio, fix personal pain point, give back
- **Preferences:** Bug fix, feature, docs, tests, refactoring
### Step 2: Project Assessment
Before searching issues, evaluate project health and read contribution guidelines:
**MANDATORY: Read CONTRIBUTING.md**
- **MUST read and understand** the repository's CONTRIBUTING.md file
- Note required workflow, branch naming, commit conventions
- Identify testing requirements and code style guidelines
- Check for CLA (Contributor License Agreement) requirements
- Understand PR submission process and review expectations
- **All subsequent phases MUST follow these guidelines**
**Health indicators:**
- Recent commit activity (last 7-30 days)
- Responsive maintainers (issue/PR response time)
- Clear contribution guidelines (CONTRIBUTING.md present)
- Active community (discussions, recent merges)
- Good documentation
**Red flags:**
- No activity for 6+ months
- Many ignored PRs or issues
- Hostile or dismissive maintainer responses
- No CONTRIBUTING.md or unclear guidelines
- Constant breaking changes
Output format:
```markdown
### Project Health Check
- **Activity:** [recent commits/releases]
- **Responsiveness:** [avg maintainer response time]
- **Community:** [# contributors, discussion activity]
- **CONTRIBUTING.md:** ✅ Read and understood / ⚠️ Unclear / ❌ Missing
- Key requirements: [workflow, testing, style, etc.]
- **Assessment:** ✅ Good to contribute / ⚠️ Proceed with caution / ❌ Not recommended
```
### Step 3: Issue Filtering
Use multiple filters to find candidates:
**Critical filters (MUST apply):**
- **No linked PR:** Exclude issues that already have associated pull requests
- Check issue references, linked PRs in GitHub UI
- Skip issues marked "has-pr" or with PR links in comments
- **Beginner-friendly priority:** Focus on accessible issues
- Labels: `good first issue`, `beginner-friendly`, `help wanted`
- Labels: `up-for-grabs`, `easy`, `low-hanging-fruit`
- **High priority labels:** Prioritize important work
- Look for: `priority: high`, `high-priority`, `important`, `urgent`
- Repository-specific priority indicators
- Issues referenced in roadmap or milestones
**By issue type:**
- `documentation`, `bug`, `enhancement`
- Prefer well-scoped, clearly defined issues
**By complexity:**
- **Simple (1-4 hours):** Typos, docs, simple bugs, config changes
- **Moderate (1-2 days):** Feature additions, refactoring, moderate bugs
- **Complex (1+ weeks):** Architecture changes, major features, complex bugs
**By recency:**
- Prefer issues updated within last 30 days
- Check for assigned developers
- Look for maintainer engagement
### Step 4: Individual Issue Evaluation
For each candidate issue, assess:
#### Quality Indicators ✅
**Clear description:**
- Problem statement is specific
- Expected behavior defined
- Actual behavior described
- Steps to reproduce (for bugs)
**Good context:**
- Relevant error messages/logs
- Environment details (version, OS, browser)
- Screenshots or examples
- Links to related issues/discussions
**Maintainer engagement:**
- Maintainer has commented
- Issue is confirmed/triaged
- No one currently assigned
- Not marked as "wontfix" or "blocked"
#### Warning Signs ⚠️
- **Has linked PR** - Issue already being worked on
- Vague or unclear requirements
- No maintainer response
- Already assigned to someone
- Marked as "blocked", "on-hold", or "needs-discussion"
- Very old issue (6+ months) with no activity
- Duplicate of another issue
- Controversial or disputed approach
#### Evaluation Template
For each candidate issue:
```markdown
## Issue: [Title] (#[number])
**URL:** [link]
**Labels:** [labels]
**Created:** [date] | **Updated:** [date]
### Quick Assessment
- **Clarity:** ⭐⭐⭐⭐☆ (4/5) - [brief note]
- **Scope:** 🔵 Small | 🟡 Medium | 🔴 Large
- **Difficulty:** 🟢 Easy | 🟡 Moderate | 🔴 Hard
- **Time estimate:** [hours/days]
### Requirements Understanding
- **What needs to be done:** [1-2 sentences]
- **Success criteria:** [how to know it's complete]
- **Unknowns:** [what's unclear or needs investigation]
### Skill Match
- **Required skills:** [list]
- **Your match:** ✅ Good fit / ⚠️ Stretch goal / ❌ Too advanced
- **Learning opportunity:** [what you'll learn]
### Decision
✅ **Good choice because:** [reasons]
⚠️ **Consider if:** [conditions]
❌ **Skip because:** [reasons]
**Recommendation:** [Proceed / Ask maintainer first / Choose another]
```
### Step 5: Multi-Issue Comparison
When evaluating multiple issues, create comparison table:
```markdown
## Issue Comparison
| Issue | Difficulty | Time | Learning Value | Impact | Priority |
|-------|-----------|------|----------------|--------|----------|
| #123 | 🟢 Easy | 2h | ⭐⭐☆ | Medium | 🥇 High |
| #456 | 🟡 Medium | 1d | ⭐⭐⭐ | High | 🥈 Med |
| #789 | 🔴 Hard | 1w | ⭐⭐⭐⭐ | High | 🥉 Low |
### Recommendation
Start with **#123** because:
1. Quick win to familiarize with codebase
2. Clear requirements, low risk
3. Sets foundation for #456 later
**Progression path:** #123 → #456 → #789
```
## Strategic Considerations
### First Contribution Strategy
For first-time contributors to a project:
1. **Start small:** Choose simple issue to learn workflow
2. **Build trust:** Demonstrate quality before tackling complex work
3. **Learn codebase:** Use first PR to understand conventions
4. **Engage community:** Interact respectfully with maintainers
**Recommended progression:**
```
First PR: Documentation fix or typo
↓
Second PR: Simple bug fix or small feature
↓
Third PR: Moderate complexity work
↓
Ongoing: Complex features, architecture improvements
```
### Learning-Oriented Selection
When goal is learning:
- **Choose stretch issues:** Slightly above comfort level
- **Look for patterns:** Issues that teach transferable skills
- **Seek feedback:** Projects with detailed code reviews
- **Diverse types:** Mix bugs, features, refactoring, docs
### Impact-Oriented Selection
When goal is maximizing value:
- **User-facing issues:** Direct user benefit
- **Bug fixes:** Immediate problem resolution
- **Documentation:** Helps many future contributors
- **Performance:** Benefits all users
### Portfolio Building
For building public portfolio:
- **Substantial features:** Show design skills
- **Complex bugs:** Show debugging ability
- **Cross-cutting work:** Show system understanding
- **Leadership:** Help triage, review others' PRs
## Engagement Before Starting
Before beginning work, **always:**
1. **Comment on issue:**
```
"Hi! I'd like to work on this issue.
My understanding is: [brief summary]
I'm planning to: [approach]
Does this sound good? Any guidance appreciated!"
```
2. **Wait for confirmation:**
- Maintainer gives go-ahead
- No one else is assigned
- Approach is approved
3. **Ask questions:**
- Clarify unclear requirements
- Confirm edge cases
- Request guidance on approach
**Why this matters:**
- Avoids duplicate work
- Ensures approach is correct
- Builds relationship with maintainers
- Shows respect for project process
## Common Pitfalls
**Avoid:**
❌ **Starting without commenting** - Someone else might be working on it
❌ **Choosing glamorous but too-hard issues** - Will frustrate you and waste time
❌ **Ignoring "needs discussion" label** - Issue might not be ready
❌ **Taking assigned issues** - Respect others' claimed work
❌ **Multiple issues at once** - Finish one before starting next
❌ **Stale issues** - May be outdated or deprioritized
## Output Format
Provide structured recommendation:
```markdown
# 🎯 Issue Discovery Results
## Selected Issue
**Title:** [Issue title]
**URL:** [link]
**Status:** [open/triaged/confirmed]
### Why This Issue?
1. [Reason 1: skill match, learning, impact, etc.]
2. [Reason 2]
3. [Reason 3]
### What You'll Do
[1-2 sentence summary of the work]
### Prerequisites
- [ ] Comment on issue to claim
- [ ] Wait for maintainer approval
- [ ] Fork repository
- [ ] Set up development environment
### Next Steps
Ready to move to **Phase 2: Issue Analysis**?
---
## Alternative Options
If this doesn't work out, consider:
1. **[Issue #]** - [brief description, why alternative]
2. **[Issue #]** - [brief description, why alternative]
```
## Integration with Main Framework
When invoked from main framework:
1. **Receive context:** User profile, project URL, preferences
2. **Execute discovery:** Filter and evaluate issues
3. **Return recommendation:** Selected issue + reasoning
4. **Update tracker:** Mark Phase 1 complete
5. **Transition:** Prepare context for Phase 2
Can be re-invoked at any time if selected issue becomes unavailable or user wants different option.

783
skills/solution-implementation/SKILL.md Normal file
View File

@@ -0,0 +1,783 @@
---
name: oss:solution-implementation
description: Phase 3 of OSS contribution - Design and implement the solution following project standards and best practices. Writes code following conventions, adds/updates tests, handles edge cases. Use when issue analysis is complete and ready to write code.
---
# Phase 3: Solution Implementation
Design and implement the solution following project standards and best practices.
## Purpose
Transform the implementation plan into working code that:
- Solves the issue completely
- Follows project conventions
- Passes all tests
- Handles edge cases
- Is maintainable and reviewable
## When to Use
**Triggers:**
- "솔루션 구현"
- "이슈 해결 시작"
- "코드 작성"
- "테스트 작성"
**Use when:**
- Issue analysis (Phase 2) is complete
- Code locations identified
- Ready to write code
- Need implementation guidance
- Want to follow best practices
## Implementation Framework
### Step 0: CONTRIBUTING.md Compliance Check
**MANDATORY: Final verification before implementation**
- Review all CONTRIBUTING.md requirements from Phase 1
- Ensure implementation will follow:
- Code style and formatting standards
- Commit message format
- Branch naming conventions
- Testing requirements
- Documentation standards
- **All code written MUST strictly follow these guidelines**
### Step 1: Implementation Planning
Plan your approach before writing code.
**Design decisions:**
```markdown
### Implementation Plan
**Approach:**
[High-level description of solution approach]
**Why this approach:**
1. [Reason 1: e.g., matches existing patterns]
2. [Reason 2: e.g., minimal invasive change]
3. [Reason 3: e.g., easily testable]
**Alternative approaches considered:**
- **[Approach A]:** [why not chosen]
- **[Approach B]:** [why not chosen]
**Implementation order:**
1. [Task 1] - [rationale for doing first]
2. [Task 2] - [builds on previous]
3. [Task 3] - [completes the feature]
**Checkpoints:**
- After step 1: [what to verify]
- After step 2: [what to verify]
- After step 3: [final verification]
```
### Step 2: Test-Driven Development (TDD)
Start with tests when possible.
**TDD workflow:**
1. **Write failing test:**
- Captures the requirement
- Specific and focused
- Fails for right reason
2. **Implement minimal solution:**
- Make test pass
- No premature optimization
- Follow existing patterns
3. **Refactor:**
- Clean up code
- Extract duplications
- Improve readability
- Tests still pass
**When TDD makes sense:**
- Bug fixes (test reproduces bug)
- New utility functions
- Clear acceptance criteria
- Well-understood requirements
**When to code first:**
- Exploratory work
- UI/UX iteration
- Complex interactions
- Unclear requirements
**Test-first template:**
```markdown
### TDD Cycle
**Red (Failing Test):**
```javascript
// test/feature.test.js
describe('NewFeature', () => {
it('should do X when Y', () => {
const result = newFeature(input)
expect(result).toBe(expected) // ❌ FAILS
})
})
```
**Green (Minimal Implementation):**
```javascript
// src/feature.js
function newFeature(input) {
// Simplest thing that makes test pass
return expected
}
```
**Refactor (Clean Up):**
```javascript
// src/feature.js
function newFeature(input) {
// Proper implementation
// Handles edge cases
// Clean and readable
return properResult
}
```
**Verify:** All tests pass ✅
```
### Step 3: Code Implementation
Write production code following project conventions.
**Quality checklist:**
```markdown
### Code Quality
**Correctness:**
- [ ] Solves the stated problem
- [ ] Handles all requirements
- [ ] Covers edge cases
- [ ] No logical errors
**Convention adherence:**
- [ ] Naming matches project style
- [ ] Formatting follows guidelines
- [ ] Imports organized correctly
- [ ] Comments where helpful
**Code quality:**
- [ ] DRY (Don't Repeat Yourself)
- [ ] Single Responsibility Principle
- [ ] Appropriate abstractions
- [ ] Clear variable/function names
**Error handling:**
- [ ] Validates inputs
- [ ] Handles errors gracefully
- [ ] Provides clear error messages
- [ ] Fails safely
**Performance:**
- [ ] No obvious inefficiencies
- [ ] Appropriate data structures
- [ ] Avoids unnecessary work
- [ ] Acceptable time/space complexity
**Security:**
- [ ] Input validation
- [ ] No injection vulnerabilities
- [ ] Proper authorization checks
- [ ] Sensitive data protection
```
**Implementation patterns:**
**For Bug Fixes:**
```markdown
### Bug Fix Implementation
**1. Add test that reproduces bug:**
```javascript
it('should handle edge case correctly', () => {
// This test currently fails
const result = buggyFunction(edgeCase)
expect(result).toBe(correctValue)
})
```
**2. Locate root cause:**
- Function: `[name]` @ [file:line]
- Problem: [what's wrong]
- Why it happens: [explanation]
**3. Implement fix:**
```javascript
// Before:
function buggyFunction(input) {
return input.value // Fails when input.value is undefined
}
// After:
function buggyFunction(input) {
return input?.value ?? defaultValue // Handles undefined
}
```
**4. Verify:**
- [ ] New test passes
- [ ] Existing tests pass
- [ ] Manual testing confirms fix
```
**For Features:**
```markdown
### Feature Implementation
**1. Define interface:**
```typescript
// Define types/interfaces first
interface NewFeature {
doSomething(param: Type): ReturnType
}
```
**2. Implement core logic:**
```javascript
function coreFunction() {
// Happy path first
// Clear, readable code
// One level of abstraction
}
```
**3. Handle edge cases:**
```javascript
function coreFunction(input) {
// Validate inputs
if (!isValid(input)) {
throw new Error('Invalid input: ...')
}
// Handle empty/null
if (isEmpty(input)) {
return defaultValue
}
// Core logic
const result = process(input)
// Post-conditions
validateResult(result)
return result
}
```
**4. Add tests for each path:**
- [ ] Happy path
- [ ] Edge cases
- [ ] Error cases
```
**For Refactoring:**
```markdown
### Refactoring Implementation
**1. Ensure test coverage:**
- [ ] Tests exist for current behavior
- [ ] Tests are comprehensive
- [ ] Tests pass before refactoring
**2. Refactor incrementally:**
**Step 1:** Extract function
```javascript
// Before:
function complexFunction() {
// Long complex code
// Mixing concerns
// Hard to understand
}
// After Step 1:
function complexFunction() {
const data = fetchData()
const processed = processData(data)
return formatOutput(processed)
}
function fetchData() { /* extracted */ }
function processData(data) { /* extracted */ }
function formatOutput(processed) { /* extracted */ }
```
**Step 2:** Improve naming
**Step 3:** Remove duplication
**Step 4:** Simplify logic
**After each step:**
- [ ] Tests still pass
- [ ] Code is more readable
- [ ] Behavior unchanged
```
### Step 4: Test Implementation
Write comprehensive tests.
**Test coverage goals:**
```markdown
### Test Strategy
**Unit tests:** (test individual functions)
- Location: [where tests go]
- Coverage target: [percentage or specific cases]
**Test cases:**
**Happy path:**
```javascript
it('should work with valid input', () => {
expect(feature(validInput)).toBe(expected)
})
```
**Edge cases:**
```javascript
it('should handle empty input', () => {
expect(feature([])).toBe(defaultValue)
})
it('should handle null input', () => {
expect(feature(null)).toThrow('Invalid input')
})
it('should handle large input', () => {
const largeInput = generateLargeData()
expect(feature(largeInput)).toBeDefined()
})
```
**Error cases:**
```javascript
it('should throw on invalid input', () => {
expect(() => feature(invalid)).toThrow()
})
it('should provide clear error message', () => {
expect(() => feature(invalid))
.toThrow('Expected X but got Y')
})
```
**Integration tests:** (if needed)
```javascript
it('should integrate with existing feature', () => {
// Test feature working with other parts
})
```
**Snapshot tests:** (for UI, if applicable)
```javascript
it('should render correctly', () => {
const tree = renderer.create(<Component />).toJSON()
expect(tree).toMatchSnapshot()
})
```
```
**Test best practices:**
```markdown
### Test Quality
**Clear and focused:**
- [ ] One assertion per test (generally)
- [ ] Clear test names describe behavior
- [ ] Tests are independent
- [ ] No test interdependencies
**Readable:**
- [ ] Arrange-Act-Assert structure
- [ ] Descriptive variable names
- [ ] Comments for complex setups
- [ ] DRY (use helpers/fixtures)
**Maintainable:**
- [ ] Tests don't test implementation details
- [ ] Tests are resilient to refactoring
- [ ] Test data is realistic
- [ ] Mocks/stubs are minimal
**Fast:**
- [ ] Unit tests run quickly
- [ ] Minimal external dependencies
- [ ] No unnecessary setup/teardown
```
### Step 5: Local Verification
Test thoroughly before committing.
**Verification checklist:**
```markdown
### Local Testing
**Build:**
```bash
# Clean build
[build command]
# Check for warnings
[any warnings to address?]
```
**Tests:**
```bash
# Run all tests
[test command]
# ✅ All pass
# Run with coverage
[coverage command]
# ✅ Coverage meets threshold
# Run specific affected tests
[command for affected tests]
# ✅ Pass
```
**Linting:**
```bash
# Check code style
[lint command]
# ✅ No errors
# Auto-fix if available
[format command]
```
**Type checking (if applicable):**
```bash
[type check command]
# ✅ No type errors
```
**Manual testing:**
- [ ] Feature works as expected
- [ ] Edge cases handled
- [ ] Error messages clear
- [ ] UI looks correct (if applicable)
- [ ] Performance acceptable
**Regression check:**
- [ ] Existing features still work
- [ ] No unintended side effects
- [ ] Related functionality intact
```
### Step 6: Code Review Self-Check
Review your own code before submitting.
**Self-review checklist:**
```markdown
### Self Code Review
**Completeness:**
- [ ] All requirements implemented
- [ ] All edge cases handled
- [ ] All acceptance criteria met
- [ ] No TODO/FIXME left unaddressed
**Code quality:**
- [ ] Code is self-explanatory
- [ ] Complex parts have comments
- [ ] No dead code or commented-out code
- [ ] No debugging code (console.log, etc)
**Changes are minimal:**
- [ ] Only changed what's necessary
- [ ] No unrelated refactoring
- [ ] No formatting-only changes mixed in
- [ ] Git diff is clean and focused
**Testing:**
- [ ] Tests are comprehensive
- [ ] Tests are meaningful (not just for coverage)
- [ ] Tests pass consistently
- [ ] Edge cases have tests
**Documentation:**
- [ ] Public APIs documented
- [ ] Complex logic explained
- [ ] README updated if needed
- [ ] Migration guide if breaking
**Security:**
- [ ] No secrets/credentials committed
- [ ] User input validated
- [ ] No obvious vulnerabilities
- [ ] Dependencies are safe
**Performance:**
- [ ] No performance regressions
- [ ] Algorithms are efficient
- [ ] Resource usage reasonable
- [ ] No memory leaks
**Commits:**
- [ ] Commits are logical
- [ ] Commit messages are clear
- [ ] No merge commits from main (rebase if needed)
- [ ] History is clean
```
### Step 7: Documentation
Document your changes appropriately.
**Documentation types:**
```markdown
### Documentation Updates
**Code comments:**
```javascript
/**
* Converts user data to CSV format
*
* @param {User[]} users - Array of user objects
* @param {ExportOptions} options - Export configuration
* @returns {string} CSV formatted string
* @throws {ValidationError} If users array is invalid
*
* @example
* const csv = exportToCSV(users, { includeHeaders: true })
*/
function exportToCSV(users, options) {
// Implementation
}
```
**README updates:**
- [ ] New features documented
- [ ] Usage examples added
- [ ] Installation steps updated
- [ ] API changes reflected
**CHANGELOG:**
- [ ] Entry added with:
- Version (if applicable)
- Date
- Type: [Added/Changed/Fixed/Removed]
- Description
```markdown
## [Unreleased]
### Added
- Export to CSV functionality (#123)
- New `exportToCSV` function
- Customizable column selection
- Header row optional
```
**API documentation:**
- [ ] New endpoints documented
- [ ] Parameters described
- [ ] Response format specified
- [ ] Error codes listed
- [ ] Examples provided
**Migration guide (if breaking):**
```markdown
## Migrating to v2.0
### Breaking Changes
**Function signature changed:**
```javascript
// Old:
doSomething(param)
// New:
doSomething(param, options)
```
**Migration steps:**
1. Find all calls to `doSomething`
2. Add empty options object: `doSomething(param, {})`
3. Configure options as needed
```
```
## Implementation Best Practices
**Start small:**
- Implement core functionality first
- Add features incrementally
- Test each increment
- Commit working states
**Follow patterns:**
- Match existing code style
- Use same abstractions
- Don't introduce new paradigms
- Be consistent
**Communicate:**
- Ask questions early
- Share progress on complex issues
- Discuss tradeoffs
- Welcome feedback
**Iterate:**
- Don't aim for perfection first try
- Reviewers will have feedback
- Be open to changes
- Learn from reviews
## Common Pitfalls
**Avoid:**
❌ **Scope creep** - Stick to issue requirements
❌ **Over-engineering** - Keep it simple
❌ **Ignoring conventions** - Match project style
❌ **Skipping tests** - Tests are requirements
❌ **Poor commit messages** - Future you will be confused
❌ **Not testing edge cases** - Where bugs hide
❌ **Mixing concerns** - One logical change per commit
❌ **Committing secrets** - Check before pushing
## Output Format
Provide implementation summary:
```markdown
# ✅ Implementation Complete: [Issue Title]
**Issue:** #[number]
**Branch:** [branch-name]
---
## Changes Made
### Core Implementation
**1. [Primary change]**
- File: `[path]`
- Changes: [description]
- Lines modified: ~[count]
**2. [Secondary change]**
- File: `[path]`
- Changes: [description]
### Tests Added
**Unit tests:**
- `[test-file]` - [N] test cases
- Happy path
- Edge cases: [list]
- Error cases: [list]
**Coverage:** [percentage] (previous: [X]%, delta: +[Y]%)
### Documentation
- [ ] Code comments added
- [ ] README updated
- [ ] CHANGELOG entry added
- [ ] API docs updated
---
## Verification
**Local testing:**
- ✅ All tests pass
- ✅ Linting passes
- ✅ Build succeeds
- ✅ Manual testing complete
**Checklist:**
- ✅ Requirements met
- ✅ Edge cases handled
- ✅ Follows conventions
- ✅ Self-review complete
---
## Commits
```bash
# Commit history
git log --oneline origin/main..HEAD
```
**Summary:**
- [N] commits
- All commits are focused and logical
- Commit messages are clear
---
## Next Steps
✅ Implementation complete - Ready for **Phase 4: Documentation & PR**
**Before PR:**
- [ ] Final review
- [ ] Rebase on main (if needed)
- [ ] Squash commits (if needed)
- [ ] Push to remote
```
## Integration with Main Framework
When invoked from main framework:
1. **Receive context:** Issue analysis from Phase 2, requirements, code locations
2. **Guide implementation:** Step-by-step with quality checks
3. **Verify completion:** All requirements met, tests pass
4. **Return summary:** What was implemented and how
5. **Update tracker:** Mark Phase 3 complete
6. **Transition:** Ready for documentation and PR creation
Implementation phase may iterate with Phase 2 if code structure different than expected.
## Incremental Development
**For large implementations:**
1. **Milestone 1:** Core functionality
- Implement minimal working version
- Add basic tests
- Commit: "feat: add core X functionality"
2. **Milestone 2:** Edge cases
- Handle edge cases
- Add edge case tests
- Commit: "feat: handle X edge cases"
3. **Milestone 3:** Polish
- Error messages
- Documentation
- Commit: "docs: add X documentation"
**Benefits:**
- Can get early feedback
- Easier to review
- Simpler to debug
- Clear progress tracking