Skip to content
Thoth Tech

Peer Review Guide

Introduction on how to do a peer review within the Ontrack Web Dev Team

In Ontrack, peer reviews are a vital process to ensure code quality, maintainability, and consistency across the website development project. Every pull request (PR) must follow the Peer-Review Checklist, which checks for key factors like functionality, code readability, and documentation.

Additionally, the Peer-Review Prompts serve as a conversation starter for reviewers, encouraging collaboration while allowing for a thorough and constructive review process.

Ontrack Peer-Review Checklist

The following checklist is required to be completed for every review to ensure high-quality contributions.

## General Information


- [ ] Type of Change: Clearly indicate the type of change (choose one):
  - [ ] Bug fix
  - [ ] New feature
  - [ ] Breaking change
  - [ ] Documentation update


## Code Quality


- [ ] Repository: Ensure the PR is made to the correct repository.
- [ ] Readability: Is the code easy to read and follow? Are comments included where necessary?
- [ ] Maintainability: Can this code be maintained or extended easily in the future?


## Functionality


- [ ] Correctness: Does the code meet the task requirements?
- [ ] Existing Functionality: Has the impact on existing functionality been considered and tested?


## Testing


- [ ] Test Coverage: Are unit tests provided for new or modified code?
- [ ] Test Results: Have all tests passed successfully?


## Documentation


- [ ] Documentation: Is the inline and external documentation updated and clear?


## Pull Request Details


- [ ] PR Description: Is the problem being solved clearly described?
- [ ] Checklist Completion: Have all relevant checklist items been reviewed and completed?

Ontrack Peer-Review Prompts

  • General Information:

    • Type of Change: Clearly indicate the type of change (choose one):
      • Bug fix
      • New feature
      • Breaking change
      • Documentation update

  • Code Quality:

    • Repository: Ensure the PR is made to the correct repository.
    • Readability: Is the code easy to read and follow? Are comments included where necessary?
    • Maintainability: Can this code be maintained or extended easily in the future?

  • Functionality:

    • Correctness: Does the code meet the task requirements?
    • Existing Functionality: Has the impact on existing functionality been considered and tested?

  • Testing:

    • Test Coverage: Are unit tests provided for new or modified code?
    • Test Results: Have all tests passed successfully?

  • Documentation:

    • Documentation: Is the inline and external documentation updated and clear?

  • Pull Request Details:

    • PR Description: Is the problem being solved clearly described?
    • Checklist Completion: Have all relevant checklist items been reviewed and completed?

OnTrack Peer-Review Prompts

Use these prompts to guide discussions and ensure high-quality code contributions:

  • Type of Change: Is the PR correctly identifying the type of change (bug fix, new feature, etc.)?
  • Code Readability: Is the code well-structured and easy to follow? Could better comments, names, or organization improve it?
  • Maintainability: Is the code modular and easy to maintain? Does it introduce any technical debt?
  • Code Simplicity: Are there redundant or overly complex parts of the code that could be simplified?
  • Edge Cases: Does the code account for edge cases? What scenarios might cause it to break?
  • Test Thoroughness: Does the testing cover all edge cases and failure paths? Are there enough tests to ensure code reliability?
  • Backward Compatibility: Does the change break any existing functionality? If so, is backward compatibility handled or documented?
  • Performance Considerations: Could this code impact performance negatively? Can it be optimized while maintaining readability?
  • Security Concerns: Does this change introduce any security risks? Is input validation handled properly?
  • Dependencies: Are new dependencies necessary? Could they conflict with existing libraries? Could this functionality be achieved without new dependencies?
  • Documentation: Is the documentation clear and thorough enough for new developers to understand? Does it cover API or external interface changes?

Review Guidelines for Specific File Types

.mdx Files

  • Content Accuracy: Ensure that the content is clear and accurate. Double-check for any errors in documentation or guides.
  • Frontmatter: Ensure the frontmatter (title, description, etc.) is correctly filled out.
  • Component Usage: Verify that components like LinkCard or CardGrid are used appropriately within .mdx files.

.css Files

  • Consistency: Check alignment with the Styling Guide and consistent use of variables (e.g., colors, fonts, spacing).
  • Accessibility: Ensure animations respect user preferences, and contrast ratios meet WCAG 2.1 AA standards.
  • Naming Conventions: Verify CSS class names follow consistent patterns.

.jsx/.tsx Files

  • Functionality: Validate that interactive components (e.g., forms, sliders) work as expected and meet task requirements.
  • Performance: Identify unnecessary re-renders or performance concerns.
  • Code Style: Ensure compliance with React/JSX best practices and linting rules.

.astro Files

  • Structure: Verify page/component structure aligns with Astro standards.
  • Reusability: Look for repetitive code that could be refactored into reusable components.

Useful Resources for Reviewers

By following these guidelines, you’ll help maintain high standards of code quality, performance, and accessibility in the OnTrack project. Peer reviews not only ensure the quality of the code but also foster collaboration and shared learning among the team.