Skip to content

pr review guidelines

Jump to bottom
Ditwan Price edited this page Sep 27, 2024 · 3 revisions

tags: [dev, pull request, pr, review, conventions]

PR Review Guidelines

This document aims to provide a set of guidelines to encourage developers to submit more pull request (PR) reviews. Adhering to the guidelines will improve the consistency and quality of our code and make sure we are all on the same page.

Types of reviews and suggested workflows

  • Automated dependency updates -- these are typically straightforward and only require approval before merging.
    • if a check is failing
      • if it's something impacted by your changes, please address the failure in order to help the PR move along
      • if it's something complicated, needs more time or is related to test instability, comment on the PR about any findings and bring this up in the core channel, where we will either
        • provide assistance or
        • get confirmation to create a follow-up issue
  • Documentation updates
  • If there are visual changes associated with a PR
    • make sure to apply the pr ready for screenshot tests label
      • if there are additional visual changes since the last screenshot test run, this label will need to be removed then added again to schedule another test run
    • mention @SkyeSeitz and @ashetland to approve screenshot updates
  • If a follow-up issue is needed during the PR review
    • mention @geospatialem, @brittneytewks, so a related issue can be created, estimated, and prioritized for an upcoming milestone
    • provide context and details for the new issue(s) to better we prepare ourselves for future follow-up work
  • If PR checks are failing unexpectedly

Deprecation PRs

When a pull request is strictly intended to deprecate an existing feature or component, use the deprecate commit type. This type is reserved for noting changes under the "Deprecations" section of the changelog.

If deprecations are part of a broader change, such as introducing a new feat or making a fix, a deprecate entry can be added to the bottom of the PR body following the format described in the release-please documentation.

Example

PR title:

feat(avatar): add in an awesome new feature ✨

Description:

This PR adds in feature x which will make everything work flawlessly forever. 

deprecate(avatar): remove old unnecessary property 🗑️

⚠️ Make sure to always add the deprecate entry at the bottom of the PR body as shown above.

Reviewing

  • In addition to requesting a review on GitHub, the quickest way to get attention for your PR is to post a message in the Core - Development Teams channel.
  • Before starting a review on a non-draft PR (see Draft PRs below), use the 👀 reaction to let others know the PR is being reviewed.

Draft PRs

PRs in a draft state should not be reviewed unless explicitly asked to. This is done to minimize time focusing on code that might change.

Comments

When commenting, it is crucial to provide the (PR) author with the priority/context of each comment, e.g., what must be changed, what's a nice-to-have, etc.

Use the following syntax to shed light on the type of comment:

  • Nitpick: minor adjustments that shouldn't prevent merging
  • Suggestion: alternative approach that shouldn't prevent merging
  • Sidebar: a relevant note that is not critical to the reviewed PR (should either stem a discussion or an issue/PR to follow-up)
  • Typo: address typographical errors (these should be fixed before merging)

Be as specific as possible in your comments to offer reasoning and avoid misinterpretation.

If there is a lot of back-and-forth between the reviewer and author, reach out via chat or schedule a call to make sure everyone is on the same page. Once everything is resolved, make sure to summarize the discussion points and resolution in the PR before moving forward.

Considerations

Focus on the following items while reviewing:

  • Consistency (naming, patterns, etc.) 📚
  • Adhering to guidelines 🤝📚
  • If applicable, improvements or alternatives to a solution
  • Typos and grammar
  • PR title adheres to conventional commits 🤝
  • Ensure all files are relevant to the associated issue
  • Make sure to ask clarifying questions about changes if you don't understand something. This helps share the knowledge and can help identify information that might be useful to add as comments or rename variables/functions to make the code clearer.

The contributing 🤝 and conventions 📚 doc are excellent resources with additional information on the above.

Submitting

You can approve a review if there are a couple required changes, as long as they are straightforward. However, make sure to "request changes" if the changes require a second pass from you.

It's always better to be explicit and comment whether the PR is good to merge after making adjustments or if you'd like to be requested for another review once changes have been made.

Getting extra pairs of eyes on reviews is always a good idea, but not necessary. If you'd like to get someone else to take a look, please mention them or add them as reviewers. Similarly, if you are unfamiliar with the changes, please call this out to give a better idea on whether additional reviewers may be needed. If you're unsure on who to contact, refer to the Areas of Focus page for guidance.

Home

Tokens

Clone this wiki locally