---
title: "Review Process"
description: "How reviews work."
---

## Code Review Workflow

The pull request review process ensures code quality, consistency, and maintainability. Here's what happens at each stage:

### 1. Pull Request Submission

Before submitting for review, ensure:
- All local tests pass: `bun run test:run`
- Code is formatted: `bun run lint:fix`
- Types check: `bun run type-check`
- Commit messages follow conventions (see [Commit Messages](/docs/03-development/03-contributing/04-commit-messages))
- PR description explains the change and why it's needed
- Related issues are linked: "Closes #123"

### 2. Automated Checks

Once submitted, automated checks run:
- **Linting:** Code style compliance
- **Type checking:** TypeScript/Python type validation
- **Unit tests:** Coverage >80% for new code
- **Integration tests:** End-to-end functionality
- **Security scanning:** Vulnerability detection
- **Performance:** Build size and runtime impact

All checks must pass before human reviewers look at the code.

### 3. Human Review

One or two maintainers will review your code for:
- **Correctness:** Does it solve the problem correctly?
- **Clarity:** Is the code easy to understand?
- **Tests:** Are new behaviors covered by tests?
- **Documentation:** Are changes documented?
- **Performance:** Any performance implications?
- **Security:** Following security best practices?

Review timeline: 24-48 hours for normal priority PRs

### 4. Review Feedback

Reviewers will use standardized comments:
- **Request changes:** Must fix before merge
- **Comment:** Suggestion for improvement
- **Approve:** Code is ready to merge

Address feedback by:
1. Responding to each comment
2. Making code changes
3. Pushing to the same branch
4. Requesting re-review

### 5. Approval and Merge

PR can merge when:
- All automated checks pass
- At least 1 maintainer approval
- All review conversations resolved
- Branch is up to date with main
- CHANGELOG updated (if user-facing)

## Reviewer Expectations

Reviewers will evaluate:

**Code Quality**
- Follows project style guide
- No unnecessary complexity
- Functions have single responsibility
- Error handling is comprehensive

**Testing**
- New functionality has tests
- Edge cases are covered
- Tests are meaningful (not just coverage)
- Setup/teardown is clean

**Documentation**
- Code comments explain "why", not "what"
- Docstrings are complete
- User-facing docs updated
- Examples provided for new features

**Performance & Security**
- No obvious performance regressions
- Database queries are optimized
- Authentication/authorization checks present
- No secrets in code or comments

**Maintainability**
- Consistent with existing patterns
- No dead code left behind
- Dependencies are necessary
- Commit history is clean

## Author Responsibilities

Before submitting PR:

- [ ] Read and follow style guide
- [ ] Add tests for new functionality
- [ ] Verify tests pass locally
- [ ] Run linter and type checker
- [ ] Update relevant documentation
- [ ] Add CHANGELOG entry
- [ ] Keep commits focused and well-messaged
- [ ] Rebase on latest main

## Common Review Comments

**Code style:**
- "Can you follow the naming convention used elsewhere?"
- "This function is getting long, consider extracting"

**Testing:**
- "Can you add a test for this edge case?"
- "What happens if this parameter is null?"

**Documentation:**
- "Please add a docstring explaining this function"
- "Update the README since this changes user behavior"

**Performance:**
- "This could have N+1 query issues"
- "Consider caching this result"

**Security:**
- "Make sure to validate this user input"
- "This endpoint needs authentication check"

## Addressing Disagreements

If you disagree with feedback:

1. **Discuss professionally** - Explain your perspective
2. **Consider the reviewer's point** - They may see issues you missed
3. **Research alternatives** - Is there a better approach?
4. **Compromise** - Find middle ground if both have merit
5. **Escalate if needed** - Ask for a maintainer decision

Reviewers will explain their reasoning. The goal is improving code, not winning arguments.

## Merge Criteria Checklist

- [ ] All CI checks pass (green status)
- [ ] At least 1 approval from maintainer
- [ ] No changes requested (all addressed)
- [ ] All conversations marked resolved
- [ ] CHANGELOG updated (if applicable)
- [ ] No conflicts with main branch
- [ ] Squashed or rebased commits (if needed)
- [ ] Branch deleted after merge (automatic)

## Best Practices

**As an author:**
- Keep PRs small (under 400 lines if possible)
- Link related issues for context
- Respond promptly to feedback
- Be gracious about critique

**As a reviewer:**
- Be constructive and kind
- Explain the "why" not just "fix this"
- Acknowledge good code
- Review within 24 hours if possible

**For all:**
- Aim for quality over speed
- Collaborative process, not confrontational
- Focused on making TracerTM better
