Skip to main content

System Design Reviews

Overview​

System design reviews allow you to discuss your proposed solutions with your team, review potential consequences, and ensure everyone is aligned before making changes.

You can move fast, safely and confidently, without breaking things.

When to Request a Design Review​

Whenever you need a sanity check or in-depth system design discussion with your team, you can request a design review. Here are a few scenarios when this tool is helpful:

  • Explore new ideas safely with your team
  • Align your team on the design of a new feature
  • Discuss the impact of the refactoring of your system architecture
  • Review how a fix will affect system components, avoiding last minute surprises
  • Visualize upstream and downstream dependencies of a new service
  • Proactively let your QA and Ops teams know the changes coming down the pipeline

Request a Design Review​

  • Create a new design branch
  • Click “Request a Review”
  • Enter your teammate(s) email address or select existing users from the list
  • Click “Send Invitation”

You can also skip inviting your teammates and continue with the implementation of your changes to platforms, components, notebooks, sketches, environments, etc.

Comment on Design Reviews and Active Branches​

Software architecture isn't about right or wrong; it's about trade-offs, understanding requirements, and aligning goals across teams.

To have effective discussions around architectural proposals you can comment on any of your active branches or design reviews by following these steps:

  • Open your project
  • Click on “main” in the top navigation bar. If you’re currently viewing a design branch, this is where you will see the name of the new branch
  • In the right-side panel that opens select your branch
  • Click “Request changes” and leave a comment
  • Click “Request design review”

"Main" branches cannot be submitted for design review, you can only leave comments. You need to create a new design branch to make changes and request a review.

Merge a Design Review​

Once you are ready to merge your changes into the main design branch, you have two options:

(1) You don’t need team input​

  • Click the drop down arrow next to “Request a Review”
  • Select “Merge”
  • Review your changes and click “Merge”

(2) You and your team have finished reviewing the changes​

  • Select “Merge”
  • Review your changes and click “Merge”

Next Steps​

You did it! What’s next?