Initial commit
This commit is contained in:
Zhongwei Li
266
references/pr-template.md
Normal file
266
references/pr-template.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# Pull Request Template
|
||||
|
||||
Use this template when creating pull requests to open source projects. Adapt as needed based on the project's CONTRIBUTING.md guidelines.
|
||||
|
||||
---
|
||||
|
||||
## Standard PR Template (What/Why/How)
|
||||
|
||||
```markdown
|
||||
## What?
|
||||
[Brief, clear description of what this PR does - 1-2 sentences]
|
||||
|
||||
## Why?
|
||||
[Explain the reasoning, problem being solved, or business value - 2-3 sentences]
|
||||
|
||||
## How?
|
||||
[Describe the implementation approach and key decisions - bullet points work well]
|
||||
- Key change 1
|
||||
- Key change 2
|
||||
- Key change 3
|
||||
|
||||
## Testing
|
||||
[Step-by-step instructions for reviewers to test the changes]
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Expected result
|
||||
|
||||
## Checklist
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Documentation updated
|
||||
- [ ] CI passing
|
||||
- [ ] Breaking changes documented (if any)
|
||||
- [ ] Follows project code style
|
||||
|
||||
## Related Issues
|
||||
Closes #[issue number]
|
||||
Relates to #[issue number]
|
||||
|
||||
## Screenshots (if applicable)
|
||||
[Add screenshots for visual changes, UI updates, or bug fixes]
|
||||
|
||||
## Additional Notes
|
||||
[Any other context, concerns, or questions for reviewers]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Feature Addition
|
||||
|
||||
```markdown
|
||||
## What?
|
||||
Add OAuth2 authentication support for Google and GitHub providers
|
||||
|
||||
## Why?
|
||||
Users have requested social login to reduce friction during signup. This implements Key Result 2 of Q4 OKR1 and addresses multiple user requests from issue #234.
|
||||
|
||||
## How?
|
||||
- Implemented OAuth2 flow using passport.js strategy pattern
|
||||
- Added provider configuration via environment variables
|
||||
- Created callback routes for each provider (/auth/google/callback, /auth/github/callback)
|
||||
- Updated user model to link social accounts with existing email-based accounts
|
||||
- Added middleware to merge accounts if user already exists
|
||||
|
||||
## Testing
|
||||
1. Set up OAuth apps in Google and GitHub developer consoles
|
||||
2. Add credentials to `.env` file (see `.env.example` for required variables)
|
||||
3. Run `npm install` to ensure passport dependencies are installed
|
||||
4. Start server: `npm start`
|
||||
5. Navigate to `/login`
|
||||
6. Click "Login with Google" button
|
||||
7. Verify OAuth flow redirects correctly
|
||||
8. Verify user profile data merges correctly with existing account (if applicable)
|
||||
9. Test GitHub provider following same steps
|
||||
|
||||
## Checklist
|
||||
- [x] Tests added for OAuth flow (see tests/auth/oauth.test.js)
|
||||
- [x] Documentation updated (see docs/authentication.md)
|
||||
- [x] CI passing
|
||||
- [x] No breaking changes
|
||||
- [x] Follows existing code style
|
||||
- [x] Environment variables documented in .env.example
|
||||
|
||||
## Related Issues
|
||||
Closes #234
|
||||
Relates to #156 (social login epic)
|
||||
|
||||
## Screenshots
|
||||
|
||||
*New social login buttons on login page*
|
||||
|
||||
## Additional Notes
|
||||
- Chose passport.js over custom implementation for security and maintenance
|
||||
- Used strategy pattern to make adding new providers easier in future
|
||||
- Account merging happens automatically based on email address
|
||||
- Consider adding rate limiting for OAuth endpoints in future PR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Bug Fix
|
||||
|
||||
```markdown
|
||||
## What?
|
||||
Fix memory leak in worker process shutdown
|
||||
|
||||
## Why?
|
||||
The worker pool wasn't properly cleaning up connections when shutting down gracefully, leading to memory leaks over time. This was causing production issues on long-running instances and reported in #456.
|
||||
|
||||
## How?
|
||||
- Added connection cleanup in worker shutdown handler
|
||||
- Implemented timeout for graceful shutdown (30s default)
|
||||
- Added mutex locks to prevent race conditions during cleanup
|
||||
- Updated tests to verify proper cleanup
|
||||
|
||||
## Testing
|
||||
1. Run load test: `npm run test:load`
|
||||
2. Monitor memory usage: `npm run monitor:memory`
|
||||
3. Trigger graceful shutdown: `kill -SIGTERM <pid>`
|
||||
4. Verify memory is released (check monitor output)
|
||||
5. Run for 24 hours to verify no gradual memory increase
|
||||
|
||||
Manual testing:
|
||||
- Tested on staging for 48 hours with production load
|
||||
- Memory usage remained stable at ~120MB
|
||||
- Previous behavior showed gradual increase to 2GB+ over 24h
|
||||
|
||||
## Checklist
|
||||
- [x] Tests added for shutdown cleanup
|
||||
- [x] Documentation updated (shutdown behavior in README)
|
||||
- [x] CI passing
|
||||
- [x] No breaking changes
|
||||
- [x] Tested on staging environment
|
||||
|
||||
## Related Issues
|
||||
Fixes #456
|
||||
|
||||
## Additional Notes
|
||||
- Considered force-killing workers after timeout, but went with graceful degradation
|
||||
- Mutex implementation follows existing pattern in connection-pool.js
|
||||
- Backward compatible with existing shutdown handlers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Refactoring
|
||||
|
||||
```markdown
|
||||
## What?
|
||||
Refactor authentication middleware to improve testability and reduce duplication
|
||||
|
||||
## Why?
|
||||
The authentication logic was duplicated across 5 different route handlers, making it difficult to test and maintain. This refactoring consolidates the logic into reusable middleware.
|
||||
|
||||
## How?
|
||||
- Extracted auth logic into `middleware/authenticate.js`
|
||||
- Created composable middleware functions:
|
||||
- `requireAuth()` - Basic authentication check
|
||||
- `requireRole(role)` - Role-based access control
|
||||
- `optionalAuth()` - Sets user if authenticated, continues if not
|
||||
- Updated all routes to use new middleware
|
||||
- Maintained backward compatibility with existing behavior
|
||||
|
||||
## Testing
|
||||
1. Run full test suite: `npm test`
|
||||
2. Verify authentication still works:
|
||||
- Try accessing protected route without token (should get 401)
|
||||
- Access with valid token (should succeed)
|
||||
- Access with invalid token (should get 401)
|
||||
3. Verify role-based access:
|
||||
- User role trying admin endpoint (should get 403)
|
||||
- Admin role trying admin endpoint (should succeed)
|
||||
|
||||
All existing tests pass without modification, demonstrating backward compatibility.
|
||||
|
||||
## Checklist
|
||||
- [x] All existing tests pass
|
||||
- [x] Added tests for new middleware functions
|
||||
- [x] Documentation updated
|
||||
- [x] CI passing
|
||||
- [x] No breaking changes
|
||||
- [x] Code coverage maintained
|
||||
|
||||
## Related Issues
|
||||
Relates to #301 (technical debt epic)
|
||||
|
||||
## Additional Notes
|
||||
- No changes to API contracts - purely internal refactoring
|
||||
- Reduces code duplication from ~200 lines to ~50 lines
|
||||
- Future PRs can add new auth strategies more easily
|
||||
- All 5 route handlers tested individually to verify behavior unchanged
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Documentation Update
|
||||
|
||||
```markdown
|
||||
## What?
|
||||
Update installation instructions for v2.0 and add troubleshooting section
|
||||
|
||||
## Why?
|
||||
Users have reported confusion about new installation requirements in v2.0. Multiple support requests (#567, #589, #601) asking about the same issues.
|
||||
|
||||
## How?
|
||||
- Updated README.md with new installation steps
|
||||
- Added prerequisites section (Node.js 18+, npm 9+)
|
||||
- Created troubleshooting guide for common issues
|
||||
- Added examples for different deployment scenarios
|
||||
- Fixed typos and outdated links
|
||||
|
||||
## Testing
|
||||
- Followed installation steps on fresh Ubuntu 22.04 VM
|
||||
- Tested on macOS Ventura
|
||||
- Verified all links work
|
||||
- Asked non-technical user to follow guide (successfully completed)
|
||||
|
||||
## Checklist
|
||||
- [x] All links verified working
|
||||
- [x] Code examples tested
|
||||
- [x] Markdown formatting validated
|
||||
- [x] Screenshots updated to v2.0 UI
|
||||
- [x] Spelling and grammar checked
|
||||
|
||||
## Related Issues
|
||||
Closes #567, #589, #601
|
||||
|
||||
## Screenshots
|
||||
N/A (documentation only)
|
||||
|
||||
## Additional Notes
|
||||
- Kept v1.0 migration guide in separate file (MIGRATION.md)
|
||||
- Added FAQ section based on common support questions
|
||||
- Consider adding video walkthrough in future
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips for Writing Good PR Descriptions
|
||||
|
||||
### Do:
|
||||
✅ Be specific and clear
|
||||
✅ Explain WHY, not just WHAT
|
||||
✅ Provide testing instructions
|
||||
✅ Link related issues
|
||||
✅ Include screenshots for visual changes
|
||||
✅ Note breaking changes prominently
|
||||
✅ Keep it concise but complete
|
||||
|
||||
### Don't:
|
||||
❌ Just repeat the commit message
|
||||
❌ Leave sections empty ("TODO", "TBD")
|
||||
❌ Assume reviewers know the context
|
||||
❌ Include implementation details better suited for code comments
|
||||
❌ Write a novel (keep it scannable)
|
||||
❌ Skip testing instructions
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Variations
|
||||
|
||||
Some projects have specific PR template requirements. Check for:
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md` in the repository
|
||||
- Instructions in CONTRIBUTING.md
|
||||
- Examples in recently merged PRs
|
||||
|
||||
**Always adapt this template to match project expectations.**
|
||||
Reference in New Issue
Block a user