Pull Request Process

Pull Request Process

This guide covers how to submit, review, and merge pull requests.

Before Creating a PR

1. Ensure Quality

# Build the project
npm run build

# Run linting
npm run lint

# Run tests
npm run test

2. Stay Updated

# Fetch latest changes
git fetch upstream

# Rebase your branch
git rebase upstream/main

# Resolve any conflicts

3. Clean History

Keep commits focused and meaningful:

# Squash WIP commits
git rebase -i HEAD~3  # Interactive rebase last 3 commits

Creating a Pull Request

PR Title

Use the same format as commit messages:

feat(web): Add scholarship deadline reminders
fix(api): Handle empty roster response
docs: Update API reference

PR Description

Use this template:

## Summary

Brief description of what this PR does.

## Changes

- Added feature X
- Fixed bug Y
- Updated documentation for Z

## Screenshots

(If applicable, add screenshots or GIFs)

## Testing

- [ ] Tested locally
- [ ] Build passes
- [ ] Linting passes
- [ ] Tests pass

## Related Issues

Closes #123
Related to #456

Draft PRs

Use draft PRs for:

• Work in progress
• Early feedback
• Discussion before completion

Review Process

What Reviewers Look For

1. Functionality - Does it work as intended?
2. Code Quality - Is the code clean and maintainable?
3. Tests - Are there adequate tests?
4. Documentation - Is it documented?
5. Performance - Any performance concerns?
6. Security - Any security issues?

Responding to Reviews

• Be open to feedback
• Explain your reasoning
• Ask for clarification if needed
• Update the PR based on feedback

Addressing Comments

# Make changes based on feedback
git add .
git commit -m "Address review feedback"
git push

Or amend if it’s a small fix:

git add .
git commit --amend --no-edit
git push --force-with-lease

Review Guidelines (For Reviewers)

Be Constructive

❌ "This is wrong"
✅ "Consider using X here because it handles edge case Y better"

Explain Why

❌ "Don't use var"
✅ "Prefer const/let over var for block scoping and preventing accidental reassignment"

Suggest Improvements

✅ "Nice work! One suggestion: we could simplify this with..."

Approve When Ready

Don’t block PRs for minor issues. Approve with suggestions:

Looks good! A few optional suggestions, but feel free to merge.

Merging

Requirements for Merge

• At least one approval
• All CI checks pass
• No unresolved conversations
• Branch is up to date

Merge Strategy

We use Squash and Merge:

1. Combines all commits into one
2. Keeps main branch history clean
3. Preserves detailed history in PR

After Merging

The author should:

1. Delete the feature branch
2. Close related issues (if not auto-closed)
3. Update documentation if needed

Common Scenarios

My PR Has Conflicts

# Update your branch
git fetch upstream
git rebase upstream/main

# Resolve conflicts in each file
# Then continue
git add .
git rebase --continue

# Force push (with lease for safety)
git push --force-with-lease

I Need to Make Big Changes

If review requires major changes:

1. Acknowledge the feedback
2. Close the current PR
3. Create a new branch with changes
4. Open a new PR

My PR Is Stale

If your PR has been open for a while:

1. Rebase on latest main
2. Test everything still works
3. Ping reviewers

I Want to Split My PR

If a PR is too large:

1. Identify logical groupings
2. Create separate branches for each
3. Submit multiple smaller PRs
4. Reference the original PR

PR Size Guidelines

Size	Lines Changed	Review Time
Small	< 100	Same day
Medium	100-300	1-2 days
Large	300-500	2-3 days
XL	> 500	Consider splitting

Smaller PRs are:

• Easier to review
• Less likely to have bugs
• Faster to merge
• Easier to revert if needed

Labels

Label	Meaning
ready for review	Ready for review
in progress	Still being worked on
needs changes	Changes requested
approved	Approved, ready to merge
blocked	Blocked by external factor

CI Checks

Every PR runs:

1. Build - Ensures project builds
2. Lint - Checks code style
3. Tests - Runs test suite
4. Type Check - TypeScript validation

All checks must pass before merge.

Questions?

• Tag maintainers in the PR
• Ask in Discord
• Check existing PRs for examples