# Pull Request Description Format

Well-structured PR descriptions make code reviews faster and more effective.

## Required Sections

### 1. Summary (Required)
Brief description of what changed and why.

```markdown
## Summary
Adds user authentication with JWT tokens to replace session-based auth.
Improves security and enables stateless API requests.
```

### 2. Changes (Required)
Bullet list of specific changes made.

```markdown
## Changes
- Added JWT middleware for route protection
- Created token generation and validation utilities
- Updated user login endpoint to return JWT
- Migrated 12 protected routes to use JWT auth
- Removed old session middleware
```

### 3. Testing (Required)
How the changes were tested.

```markdown
## Testing
- [ ] Unit tests added for JWT utilities (100% coverage)
- [ ] Integration tests for protected routes
- [ ] Manual testing with Postman
- [ ] Tested token expiration and refresh flow
```

### 4. Breaking Changes (If Applicable)
List any breaking changes and migration path.

```markdown
## Breaking Changes
⚠️ Session-based authentication no longer supported

**Migration:**
Clients must update to send `Authorization: Bearer <token>` header
instead of relying on session cookies.

See MIGRATION.md for detailed upgrade guide.
```

### 5. Screenshots/Videos (For UI Changes)
Visual proof of changes.

```markdown
## Screenshots
### Before
[image]

### After
[image]
```

## Optional Sections

### Related Issues/PRs
```markdown
## Related
- Closes #123
- Related to #456
- Depends on #789
```

### Deployment Notes
```markdown
## Deployment
- Requires new env var: JWT_SECRET
- Run migration: npm run migrate:auth
- Update API clients to use new auth flow
```

### Performance Impact
```markdown
## Performance
- Reduced auth overhead by 45ms per request
- Eliminated database call for session lookup
```

## Template

```markdown
## Summary
[Brief description of changes and motivation]

## Changes
- [Change 1]
- [Change 2]
- [Change 3]

## Testing
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing
- [ ] [Other verification]

## Breaking Changes
[None / List breaking changes and migration path]

## Screenshots
[If UI changes]

## Related
- Closes #[issue]
```

## Best Practices

✅ **Do:**
- Write for reviewers who don't know the context
- Explain WHY, not just WHAT
- Include testing evidence
- Flag breaking changes prominently
- Link to related issues
- Keep it concise but complete

❌ **Don't:**
- Leave description blank
- Write "fixes bug" with no details
- Assume reviewers know the context
- Hide breaking changes
- Skip testing section
- Use vague language

## Size Guidelines

- **Small PR (< 100 lines):** Brief summary + testing
- **Medium PR (100-500 lines):** Full template
- **Large PR (> 500 lines):** Consider splitting + detailed explanation

Good PR descriptions save hours of back-and-forth during review.