Docs /contributing/pull-requests

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

# 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

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

## 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:

# 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

# 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

# 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

# Check types
pnpm type:check

# Fix errors
# Update type definitions

# Verify
pnpm type:check

# Push fix
git push

🔄 Update PR After Review

Making Changes

# 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

# Make changes
git add .

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

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

Interactive Rebase (Clean History)

# 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

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

Next: Testing Guidelines →

Reading this with an agent? /docs/contributing/pull-requests.md serves the raw markdown.

All docs