# Pull Request Process

> Creating and reviewing pull requests

## 📋 Overview

This guide covers the pull request (PR) process for Izri, including PR creation, review guidelines, and merge criteria.

## 🚀 Creating a Pull Request

### 1. Prepare Your Branch

```bash
# Ensure your branch is up to date
git checkout main
git pull upstream main
git checkout your-feature-branch
git rebase main

# Run all checks
pnpm type:check
pnpm lint
pnpm format:all
pnpm test
pnpm build
```

### 2. Push Your Branch

```bash
git push origin your-feature-branch
```

### 3. Create PR on GitHub

1. Navigate to the repository on GitHub
2. Click "New Pull Request"
3. Select your branch
4. Fill in the PR template
5. Add appropriate labels
6. Request reviewers
7. Link related issues

## 📝 PR Template

### Title Format

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

# Examples:
feat(projects): add project filtering
fix(auth): resolve session timeout
docs(api): update tRPC documentation
```

### Description Template

```markdown
## Description
<!-- Clear description of what this PR does -->

## Type of Change
<!-- Check relevant boxes -->
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test additions/updates

## Related Issues
<!-- Link related issues -->
Closes #123
Fixes #456

## Changes Made
<!-- List key changes -->
- Added project filtering UI
- Implemented filter API endpoint
- Added tests for filtering logic

## Screenshots
<!-- If applicable, add screenshots -->

## Testing
<!-- Describe testing performed -->
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] E2E tests added/updated
- [ ] Manual testing completed

### Test Instructions
1. Navigate to projects page
2. Use filter dropdown
3. Verify filtered results

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added that prove fix/feature works
- [ ] New and existing tests pass
- [ ] Dependent changes merged

## Breaking Changes
<!-- If applicable, describe breaking changes and migration steps -->
None

## Additional Notes
<!-- Any additional information -->
```

## 👀 Review Process

### For PR Authors

#### Before Requesting Review

- [ ] All CI checks pass
- [ ] Code is self-reviewed
- [ ] Tests are comprehensive
- [ ] Documentation is updated
- [ ] Commits follow conventions
- [ ] No merge conflicts

#### Responding to Reviews

```
1. Be responsive to feedback
2. Ask questions if unclear
3. Make requested changes promptly
4. Request re-review after changes
5. Resolve conversations after addressing
```

### For Reviewers

#### Review Checklist

**Code Quality**:

- [ ] Code is readable and maintainable
- [ ] Logic is clear and correct
- [ ] No unnecessary complexity
- [ ] Follows project conventions
- [ ] Error handling is appropriate
- [ ] No security vulnerabilities

**Testing**:

- [ ] Tests cover new functionality
- [ ] Tests are meaningful
- [ ] Edge cases considered
- [ ] Tests pass locally

**Documentation**:

- [ ] Code comments where needed
- [ ] API documentation updated
- [ ] README updated if needed
- [ ] Migration guide if breaking

**Performance**:

- [ ] No obvious performance issues
- [ ] Database queries optimized
- [ ] No unnecessary re-renders (React)
- [ ] Proper caching implemented

#### Providing Feedback

**Use GitHub review features**:

```markdown
# Blocking issue (request changes)
❌ This will cause a memory leak. Please fix before merging.

# Suggestion (approve with comment)
💡 Consider extracting this into a separate function for reusability.

# Nitpick (approve with comment)
nit: Typo in comment: "recieve" → "receive"

# Praise (always welcome!)
✨ Great error handling here!
```

#### Review Levels

**1. LGTM (Looks Good To Me)**

- Approve without comments
- Code is ready to merge

**2. Approve with Comments**

- Minor suggestions
- Non-blocking feedback
- Can merge after addressing

**3. Request Changes**

- Blocking issues found
- Must be fixed before merge
- Re-review required

## ✅ Merge Criteria

### Requirements for Merging

**Automated Checks**:

- ✅ All CI tests pass
- ✅ No merge conflicts
- ✅ Build succeeds
- ✅ Type checking passes
- ✅ Linting passes

**Review Requirements**:

- ✅ At least 1 approval
- ✅ No requested changes
- ✅ All conversations resolved

**Quality Standards**:

- ✅ Tests added/updated
- ✅ Documentation updated
- ✅ No security issues
- ✅ Performance acceptable

### Who Can Merge

**Maintainers**: Can merge any PR meeting criteria

**Contributors**: Can merge own PRs after approval (if permissions granted)

## 🔀 Merge Strategies

### Squash and Merge (Preferred)

```
Used for most feature PRs:
- Combines all commits into one
- Clean git history
- Maintains conventional commit format
```

### Merge Commit

```
Used for:
- Release branches
- Large refactoring PRs
- When commit history matters
```

### Rebase and Merge

```
Used for:
- Small, atomic PRs
- Clean commit history
- Well-structured commits
```

## 🐛 Handling Failed Checks

### CI Failures

```bash
# Check which test failed
# in GitHub Actions output

# Run locally
pnpm test

# Fix and push
git add .
git commit -m "fix: resolve test failure"
git push
```

### Merge Conflicts

```bash
# Update from main
git checkout main
git pull upstream main

# Rebase your branch
git checkout your-feature-branch
git rebase main

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

# Force push (rebase rewrites history)
git push --force-with-lease
```

### Type Errors

```bash
# Check types
pnpm type:check

# Fix errors
# Update type definitions

# Verify
pnpm type:check

# Push fix
git push
```

## 🔄 Update PR After Review

### Making Changes

```bash
# Make requested changes
# Edit files

# Commit
git add .
git commit -m "refactor: address review feedback"

# Push
git push

# Request re-review on GitHub
```

### Amending Last Commit

```bash
# Make changes
git add .

# Amend last commit
git commit --amend --no-edit

# Force push
git push --force-with-lease
```

### Interactive Rebase (Clean History)

```bash
# Rebase last 3 commits
git rebase -i HEAD~3

# Options:
# pick - keep commit
# reword - change message
# squash - combine with previous
# fixup - combine, discard message
# drop - remove commit

# Force push
git push --force-with-lease
```

## 📊 PR Size Guidelines

### Ideal PR Size

```
Small PRs are better:
- Easier to review
- Faster to merge
- Less likely to have issues
- Easier to revert if needed

Target: < 400 lines changed
```

### Breaking Up Large PRs

```
If your PR is too large:

1. Split by feature/component
2. Create multiple PRs
3. Use feature flags
4. Stage across multiple releases
```

## ⏱️ PR Lifecycle

### Timeline

```
1. PR Created       → Day 0
2. Initial Review   → Within 1-2 days
3. Feedback Address → Within 1-2 days
4. Re-review        → Within 1 day
5. Merge            → Same day as approval
```

### Stale PRs

```
PRs inactive for 14 days may be closed:
- Comment to keep PR active
- Or push new commits
```

## 🎯 Best Practices

### Do's

✅ Keep PRs focused and small
✅ Write clear descriptions
✅ Add tests for new features
✅ Update documentation
✅ Respond to feedback promptly
✅ Be respectful in discussions
✅ Link related issues
✅ Request reviews from appropriate people

### Don'ts

❌ Don't open WIP PRs without draft label
❌ Don't commit directly to main
❌ Don't force-push after review started (unless rebasing)
❌ Don't ignore CI failures
❌ Don't merge without approval
❌ Don't include unrelated changes
❌ Don't push broken code

## 🎓 Examples

### Good PR Example

```markdown
Title: feat(projects): add project filtering

## Description
Add filtering functionality to projects page allowing users to
filter by language, framework, and date range.

## Changes Made
- Add filter UI component
- Implement tRPC query with filter params
- Add database indexes for performance
- Add tests for filtering logic

## Screenshots
[Screenshot of filter UI]

## Testing
- Added unit tests for filter logic
- Added E2E test for filter interaction
- Manual testing on dev environment

Closes #234
```

### Good Commit History

```
feat(projects): add filter UI component
feat(projects): implement filter API
test(projects): add filter tests
docs(projects): update filtering documentation
```

## 🔗 Related Documentation

- **Code Style**: [Style guidelines](./code-style.md)
- **Commit Conventions**: [Commit message format](./commit-conventions.md)
- **Testing**: [Testing guidelines](./testing-guidelines.md)

---

*Next: [Testing Guidelines](./testing-guidelines.md) →*