Reviews and suggestions

Review requests ask named colleagues to approve a document or request changes. Use a suggestion to propose specific canvas edits before they reach the shared document.

Requesting or cancelling reviews requires review:request. Deciding requires review:decide and being a named reviewer on that request. Choosing reviewers in the dialog also requires members:read.

Request a document review

1. Open the document's three-dot menu and select Request review.
2. Select one or more reviewers from the organization. You can't select yourself.
3. Select Request.

Each reviewer receives an in-app notification and an email. The Review panel lists their decisions, and the document's status becomes In review.

A review records decisions about the document. It doesn't lock the canvas or require approval before ordinary edits are saved. Use suggest mode for edits you want held back.

Record a decision

1. Open a document whose open review request names you as a reviewer who hasn't decided yet.
2. Add an Optional comment in the Review panel if you need to explain the decision.
3. Select Approve or Request changes.

The requester receives an in-app notification and an email for each decision. Review notifications aren't controlled by the mention settings in Settings.

The status becomes Approved when every reviewer approves. Any request for changes makes it Changes requested. The requester can select Cancel review in the panel to cancel the request.

Suggest canvas edits

Submitting suggestions requires docs:read; accepting or rejecting them requires docs:write.

1. Select Suggest changes above the canvas. The toolbar shows Suggest mode.
2. Make the edits. For example, change the dependency between Dispatch Service and Billing Service.
3. Select Submit suggestion.

Your drawing edits stay local while suggest mode is active. Submitting saves the suggestion and returns your canvas to its starting state; it doesn't change the shared document. Cancel discards the local suggestion. If you made no edits, nothing is submitted.

Suggest mode doesn't hold back changes applied through the YAML editor or Mermaid import.

Apply a suggestion

Open suggestions appear in Suggestions on the canvas. Each element has a change label and a colored dot: added is green, removed is red and changed is amber.

Choose Accept all to apply the whole suggestion, or Accept beside an element to apply only that element. Accepting one element also closes the suggestion, so its other edits aren't applied. Use the X icon beside Accept all to reject the suggestion without changing the canvas.

Accepted edits are saved to the document and sent to other open editors. If the suggestion is based on an older saved version, accepting marks the suggestion stale and applies nothing. Reload the current document before making a fresh suggestion in that case.