Graphden documentation

Lesson 24 — Review: propose, approve, and the protected merge

Goal: by the end of this lesson you can protect a branch with a required-approvals rule, watch it refuse an unreviewed merge, and walk a change through the propose → approve cycle until it may land.

Concepts: required approvals on the merge target, the 📤 propose / ✅ approve cycle, stale-approval dismissal, self-approval, review comments (anchored and general), suggested changes, and why a merged branch is permanent.

Prefer to be shown? This lesson exists as a guided in-editor tour: open the demo with the tour running (no sign-up), or pick Lesson 24 under Interactive tutorial in the editor’s account menu.

This lesson builds on Lesson 23 — fork, edit, diff, merge. Here the missing half: making a merge conditional on review.

The rule lives on the target

On GitHub you protect main and require approving reviews; graphden works the same way, and the knobs sit under ⋯ → ⚙ Protection… on the branch-popover row of the branch being merged into:

Approvals are target-bound and content-aware: an approval is recorded for a merge into the proposal’s base branch, and editing the proposed branch afterwards dismisses the now-stale approvals — like GitHub dismissing stale reviews on a new push.

The cycle: 📤 → ✅ → ⇢

Try it

  1. Create tutorial-release from main first. Extend const into review-demo on that owned branch and bind its :value to 1.
  2. In its branch-popover ⋯ menu choose ⚙ Protection… and set Required approvals to 1.
  3. Create tutorial-feature from the release branch. Change the value to 2, return to the release and try ⇢. The target refuses the unreviewed merge.
  4. Choose 📤 Propose for review, then Δ to read the change. In the Inspector, open the function’s 💬 thread, save a comment, then click 💬 again to reopen its answer field and save an answer in the same thread. A draft is not a saved reply.
  5. Exit comparison and approve: the badge reads 1/1.
  6. Return to the feature and change the value to 3. On the release, the earlier approval is stale and the badge reads 0/1.
  7. Compare again, read the changed value and the preserved conversation, then approve the current content. The badge returns to 1/1.
  8. ⇢ would now land the reviewed value. Finish this guided lesson without merging, return to main and delete its owned child branches.

Why the tour stops before the merge

A merge in graphden is by-reference: no rows are copied — the target simply starts reading the source branch’s version rows. That makes merges cheap, and it has a consequence worth knowing: a merged branch has become part of its target’s history and can no longer be deleted while the target exists (deleting it would silently revert the target’s merged-in content — the server refuses). In real work that permanence is the point: merged branches are the record, like merged commits. In a tutorial sandbox it means the guided tour stops one click short of ⇢, so its cleanup can still remove both branches. Lesson 23 performs an actual merge and remerge between sibling sandbox branches: removing the target releases its merge reference before the source and common base are deleted.

Where this shows up next