Pull Request Template

Title Format

Use conventional commits format:

<type>(<scope>): <description>

Examples: - feat(auth): add JWT token authentication - fix(payment): resolve gateway timeout issue - docs(api): update endpoint documentation - refactor(database): optimize user query performance

Standard PR Template

Create .github/pull_request_template.md in your repository:

## ClickUp Task
CU-

> **Note:** Task ID is required for ClickUp automation. Format: `CU-abc123`
>
> Optional: Add status update syntax to auto-update task status:
> - `#CU-abc123[in review]` - Updates task to "In Review"
> - `#CU-abc123[ready for qa]` - Updates task to "Ready for QA"

## What Changed
Brief description of what was changed and why.

## Type
- [ ] Bug Fix
- [ ] New Feature
- [ ] Refactoring
- [ ] Documentation

## Testing
- [ ] Tests added/updated
- [ ] Manual testing completed

## Documentation Changes (if applicable)
- [ ] Followed guidelines in CONTRIBUTING.md (at repository root)
- [ ] All code examples tested and working
- [ ] Mermaid diagrams include alt text for accessibility
- [ ] Ran `mkdocs build` successfully
- [ ] Updated navigation in mkdocs.yml (if new page added)

## Review Focus
What should reviewers pay attention to?

## Related Issues
Closes #CU-

> **Note:** Use `Closes #CU-abc123` to automatically link and update ClickUp task.
> See [GitHub-ClickUp Integration Workflow](../03-integrations/github-clickup-workflow.md) for details.

Example PRs

Bug Fix Example

## ClickUp Task
CU-abc123

## What Changed
Fixed discount calculation bug causing negative prices when discount exceeded 100%.
Added validation to cap discount at 100% with tests for edge cases.

## Type
- [x] Bug Fix

## Testing
- [x] Added unit test for discount > 100% scenario
- [x] Manual testing with various discount values

## Review Focus
Validation logic in `calculateDiscount()` function

## Related Issues
Closes #CU-abc123

Feature Example

## ClickUp Task
CU-def456

## What Changed
Added user preference management. Users can now save and update their notification
preferences through new settings page.

## Type
- [x] New Feature

## Testing
- [x] Unit tests for preference API endpoints
- [x] Component tests for settings UI
- [x] Manual end-to-end testing

## Review Focus
API design and state management approach

## Related Issues
Closes #CU-def456

Refactoring Example

## What Changed
Extracted validation logic into reusable utility functions. No functional changes,
just improved code organization and reduced duplication.

## Type
- [x] Refactoring

## Testing
- [x] All existing tests pass
- [x] Code coverage maintained

## Review Focus
New utility functions in `utils/validation.ts`

## Related Issues
Part of tech debt cleanup initiative

Best Practices

Communication Over Checklists - Tell a clear story: What? Why? How? - Focus on context and reasoning - Automated quality gates (SonarQube, linting, tests) handle the rest

Good PR Description: ✅ "Fixed discount calculation bug that was causing negative prices when discount exceeded 100%. Added validation to cap discount at 100% and added test for edge case."

Avoid: ❌ "Fixed bug" (too vague) ❌ Long checklists duplicating automated checks ❌ Listing every file changed (visible in diff)

Reviewers Care About: 1. Context: Why was this needed? 2. Approach: Why this solution? 3. Trade-offs: What alternatives were considered? 4. Risk areas: What should they scrutinize?