Initial commit
This commit is contained in:
Zhongwei Li
466
references/codebase-checklist.md
Normal file
466
references/codebase-checklist.md
Normal 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
783
references/contribution-tips.md
Normal 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
714
references/issue-patterns.md
Normal 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
762
references/pr-templates.md
Normal 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.
|
||||
Reference in New Issue
Block a user