Initial commit
This commit is contained in:
Zhongwei Li
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