Skip to content

Code Review Process

Purpose

The code review process ensures that code quality is maintained, potential issues are identified early, and knowledge is shared across the team. Our process is designed to balance thorough design with rapid implementation

Steps

1. Architecture Design (When Applicable)

For new features requiring significant architectural changes:

  • Write an architecture design document.
  • Share the document with the team.
  • Use this document as the primary platform for implementation discussion and consensus.

2. Submit Pull Request (PR)

  • Write clear, concise commit messages.

  • Ensure the PR has a descriptive title and follows the PR description template:

  • Title should be in the format of [Linear issue number] - [short description of change]

  • Description should be a detailed description of the change.
  • Motivation and context for what the PR is solving should be provided.
  • Explain how the changes were tested.

  • Include relevant screenshots or videos of the changes.

  • Add relevant reviewers and labels. For applications we use patch, minor, and major label to indicate the semantic version that should be bumped when merged.

Pre-Review Checklist

  • Verify the code runs without errors.
  • Ensure all tests pass.
  • Follow coding standards and guidelines.
  • Address any relevant feedback from the Ellipsis review.

Reviewing the Code

  • Review the code for functionality, readability, and performance.
  • Check for adherence to engineering principles and best practices.
  • Provide constructive feedback and suggest improvements.

Responding to Feedback

  • Address all comments and feedback.
  • Make necessary changes and update the PR.
  • Resolve discussions once addressed.

Approval and Merge

For repo owners/project leads:

  • Can open PRs and merge without mandatory review.
  • Should still share the PR with the team for optional review and wait for feedback whenever possible or needed.

For non-repo owners:

  • Require at least one approval from a reviewer before merging.

Best Practices

  • Timely Reviews: Aim to review PRs promptly to avoid blocking progress.
  • Clear Communication: Be clear and specific in your feedback.
  • Respect and Empathy: Approach reviews with a positive and supportive attitude.
  • Design-First Approach: Focus on reaching consensus during the design stage for complex features.
  • Implementation Freedom: Allow for quicker implementation after design agreement.

Rationale

This process is designed to:

  • Achieve consensus early in the design stage for complex features.
  • Provide more freedom and speed during implementation.
  • Leverage the project lead's comprehensive understanding of the project context.
  • Prevent PRs from becoming blockers while still maintaining code quality.

This approach is effective for our current stage, where projects are small enough for leads to have a mostly full understanding of the context.