Engineering Handbook

Appearance

Review ​

All pull requests must receive a review from a non-authoring party (in the future this requirement will be satisfied by agents as well as humans). Github branch protection should enforce this requirement.

Review process ​

  1. [Requester] To request a review, post in the #engineering-reviews slack channel with a message in the format:

    :pr: [PROD-123]: Name of my task here

    https://github.com/bbcmaestro/bbcmaestro/pull/[id]

    Optionally: add :graphql: :backend: :frontend: :ruby: :ladybug: emojis to signal the type of the PR.

  2. [Reviewer] When picking up review request, place the 👀 emoji reaction so that the requester knows it’s being looked at

    If you’re going to take more than a couple of hours to complete the review, comment on the thread to manage expectations.

  3. [Reviewer] Perform the review and use Github to note your approval. The options are approve, comment, request changes.

  4. [Reviewer] Remove the 👀 reaction from the request and mark the status of your approval with a new reaction emoji:

    :approved: approved, :changes-requested: changes requested, :commented: comments added

    Often an approval will be accompanied by some non-blocking comments. In that instance, add both :approved::commented:. It’s also helpful to comment in the thread so that the requester gets a notification.

  5. [optional] [Requester] Address any feedback, comment in the thread for a re-review.

  6. [optional] [Reviewer] Re-review, update emoji status, comment in thread.

  7. [Requester] When the PR has been merged, add the :merged: emoji reaction to the request.

Turnaround ​

In normal circumstances, it is expected that you should receive a review within 24 hours of submitting your request.

If you need a quicker review, @ mention someone you think might be able to help.

When capacity is low, either due to team members being off or very busy, reviews may take longer.

TIP

To facilitate prompt and timely reviews, engineers need to proactively make time to review. A high level of reciprocity will help – making yourself available for review will encourage your peers to do the same for you.

How to prepare your review ​

Set your reviewers up for success - give them all the tools they need to do the job well:

  • Include all necessary context on the PR, either in the PR description or as comments. For example:
    • Link to the Asana ticket(s) where the work has been defined
    • Note and justify any architectural or implementation decisions that were made during the work on the ticket
    • Flag any risks in terms of performance, security, maintainability, etc.
    • Note and justify any considerations that weren’t acted on during the work on the ticket
  • Steer the reviewer into any particular areas that you think need checking
  • Include screenshots, screencasts or any prerequisites required to stand up the PR locally
  • Make yourself available for a call/huddle to discuss the work

Performing a review ​

[TODO]