The effective Pull Request checklist

Pull requests are an integral part of the software engineering process. At some point, you will either need to open your first pull request or review one submitted by a colleague. To help you navigate this essential aspect of development effectively, here’s a concise checklist or guide that can assist you in creating impactful pull requests while minimizing unnecessary feedback.

Opening a PR

When you're ready to submit a pull request, follow these steps to ensure clarity and completeness:

Preparation

• 🔘 Branching: Ensure your changes are on a separate feature branch.
• 🔘 Commit Changes: Make sure your commits are well-organized and meaningful.
• 🔘 Check Files: Review which files are included in the commit to avoid unnecessary changes.

Documentation

• 🔘 PR Description: Write a clear and concise description of what the PR does, including:
  • Purpose of the changes
  • Any relevant ticket or issue numbers
  • Key features or modifications
• 🔘 Test Plan: Outline how you tested your changes and any additional testing that may be required.
• 🔘 Migration Notes: If applicable, document any database migrations or breaking changes.

Quality Checks

Before opening the PR, ensure the following:

• 🔘 Formatting: Code is properly formatted according to project standards.
• 🔘 Type Checking: Run type checks (if applicable) to catch any type-related errors.
• 🔘 Testing: Ensure all relevant tests pass and consider adding new tests for new functionality.
• 🔘 Documentation Updates: Update any relevant documentation, such as READMEs or inline comments.

Reviewing a PR

When reviewing someone else's pull request, follow these steps to provide constructive feedback:

Initial Assessment

• 🔘 Read the PR Description: Understand what the author intended with the changes and how it relates to the associated ticket.
• 🔘 Mental Model: Formulate an idea of what you expect the changes to accomplish based on the description.
• 🔘 Diff Comparison: Mentally compare the changes in the PR with your expectations.

Code Quality Evaluation

• 🔘 Functionality Check:
  • Verify that the code meets the requirements outlined in the ticket.
  • Consider edge cases and potential side effects of the changes.
• 🔘 Code Style:
  • Review for consistency in code style and formatting.
  • Evaluate naming conventions for clarity and coherence.
• 🔘 Duplication and Complexity:
  • Look for opportunities to reduce code duplication (DRY principle).
  • Identify overly complex or coupled code that could be simplified.

Testing Review

• 🔘 Test Coverage:
  • Ensure that unit tests adequately cover new functionality.
  • Review integration and end-to-end tests if applicable.
• 🔘 Test Plan Evaluation:
  • Assess whether the outlined test plan effectively covers all scenarios.

Final Checks

• 🔘 Documentation Review:
  • Ensure that code is adequately commented where necessary.
  • Check that any relevant documentation (e.g., READMEs) is updated.
• 🔘 Constructive Feedback:
  • Provide clear, actionable feedback on areas for improvement.
  • Engage in respectful discussions with the author if there are disagreements or clarifications needed.
• 🔘 Approval Process:
  • Confirm that all your comments have been addressed before approving the PR.
  • Conduct a final review to catch any missed issues before merging.