Pull Request Standards

Standards and best practices for creating and reviewing pull requests across all FLYPILOT projects.

PR Creation

Title Format

[TICKET-###] Brief description of change

Ticket prefixes by organization:

Organization	Prefix	System
FLYPILOT	FLY-###	Linear
OMG Interactive	sc-###	Shortcut
Learned Media	Task ID	Asana

Examples:

• [FLY-123] Add user authentication flow
• [sc-456] Fix cart total calculation with discounts
• [FLY-789] Update documentation for API endpoints

Description Template

## Summary
Brief description of what this PR does.

## Changes
- Change 1
- Change 2
- Change 3

## Screenshots/Videos
[If applicable, add screenshots or videos of UI changes]

## Testing Instructions
1. Step to test
2. Another step
3. Expected result

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated (if needed)
- [ ] Tests added/updated (if applicable)

## Related Issues
Closes #FLY-123

---

PR Size Guidelines

Ideal PR Size

• Files changed: 1-10 files
• Lines changed: < 400 lines
• Review time: < 30 minutes

When PRs Get Too Large

If a PR exceeds these limits, consider:

1. Split by feature - Separate independent features
2. Split by layer - Backend, frontend, tests separately
3. Split by file type - Styles separate from logic
4. Create follow-up PRs - Mark non-blocking changes as follow-up

Smaller is Better

Smaller PRs get reviewed faster, have fewer bugs, and are easier to revert if needed.

---

Screenshots and Videos

When to Include

Always include for:

• UI changes (new components, layouts)
• Visual bug fixes
• Responsive design changes
• Animation/interaction changes

Tools

Platform	Tool	Notes
macOS	Cmd + Shift + 5	Built-in screen recording
macOS	CleanShot X	Better annotations
Windows	Snipping Tool	Built-in
Cross-platform	Loom	For longer explanations

Format

## Before
![Before screenshot](before.png)

## After
![After screenshot](after.png)

## Video Demo
[Loom link or GIF]

---

Review Process

Author Responsibilities

1. Self-review first - Review your own changes before requesting review
2. Respond promptly - Address feedback within 24 hours
3. Explain decisions - If you disagree with feedback, explain why
4. Update PR - Push fixes in new commits, don't force-push

Reviewer Responsibilities

1. Review within 24 hours - Don't block teammates
2. Be constructive - Explain why, not just what
3. Approve when ready - Don't nitpick minor issues
4. Use suggestion feature - For simple fixes

Review Comments

Good comment:

This function could be simplified using the reduce method. It would also make it easier to add new discount types in the future.

const total = items.reduce((sum, item) => sum + item.price, 0);

Poor comment:

Wrong approach.

---

Merging

Merge Strategies

Strategy	When to Use
Squash merge	Most PRs - keeps history clean
Merge commit	Large features with meaningful commits
Rebase merge	When linear history is required

FLYPILOT Default: Squash Merge

# Via GitHub CLI
gh pr merge --squash

# Commit message format after squash
[FLY-123] Add user authentication (#45)

Pre-Merge Checklist

• All status checks pass
• Required approvals obtained
• No merge conflicts
• Branch is up to date with base
• QA completed (if applicable)

---

Common PR Patterns

Feature PR

## Summary
Adds new user profile page with avatar upload and bio editing.

## Changes
- Add `ProfilePage` component
- Add avatar upload with image cropping
- Add bio editing with character count
- Add profile API endpoints

## Screenshots
[Before/After images]

## Testing
1. Navigate to /profile
2. Click "Edit Profile"
3. Upload an avatar
4. Edit bio and save
5. Verify changes persist after refresh

## Notes
Avatar images are stored in S3 and served via CloudFront.

Bug Fix PR

## Summary
Fixes issue where cart total showed incorrect amount when discount codes were applied.

## Root Cause
Discount was being applied after tax calculation instead of before.

## Fix
Moved discount application before tax calculation in `calculateTotal()`.

## Changes
- Fix discount application order in `cart.ts`
- Add unit tests for discount scenarios

## Testing
1. Add items to cart
2. Apply discount code "SAVE10"
3. Verify total shows: (subtotal - discount) * tax rate

Refactoring PR

## Summary
Refactors authentication module to use React Query for better caching and state management.

## Motivation
- Current implementation causes unnecessary re-renders
- No request deduplication
- Manual cache management is error-prone

## Changes
- Replace `useEffect` fetch with `useQuery`
- Add query keys for cache management
- Remove manual loading/error state

## Risk Assessment
- **Risk level:** Low
- **Rollback plan:** Revert commit
- **Testing:** All auth flows manually tested

---

Handling Conflicts

Prevention

1. Keep PRs small - Less chance of conflicts
2. Update frequently - Merge/rebase from base branch daily
3. Communicate - Let team know about overlapping work

Resolution

# Update your branch
git checkout your-branch
git fetch origin
git rebase origin/main

# Resolve conflicts
# Edit conflicted files
git add .
git rebase --continue

# Push (force push if rebased)
git push --force-with-lease

Force Push Safety

Always use --force-with-lease instead of --force to prevent overwriting others' changes.

---

Stale PRs

Definition

A PR is considered stale if:

• No activity for 7+ days
• Merge conflicts present
• Blocking status checks

Resolution

1. Update or close - Either update the PR or close it
2. Add "stale" label - Mark for visibility
3. Follow up - Ping author if blocking other work