Skip to content

Work / Trunk / Wiki / Concepts

branch-verify-merge

Conceptcanonicalverified 2026-10-21

CONCEPT.BRANCH-VERIFY-MERGE

Branch, verify, merge, tag

Summary

How a change moves from an idea to the approved design.

  1. Draft. Nobody creates a branch to start. Editing anything — on main or on any branch — starts a draft: your changes for this session, saved as you make them, seen only by you. The top bar always shows how many there are, and Delta mode shows them.
  2. Review. One job: turn the draft into a branch. Review lists every change, main beside your draft, with Undo on each; you name it (on Team, AI suggests the name and the description) and save it as a new branch or add it to an open branch. Nothing is merged from Review.
  3. Branch. A named, shared set of changes, made from a reviewed draft. Everything after Review happens on the branch page: three checks (synced with main, conflicts, verify), three tabs (Changes, Verify, Conflicts), and Merge to main. See The branch page below.
  4. Verify. Trunk renders the branch and compares it with a target: the captured site (the default) or a custom URL, such as a staging build.
  5. Consistency score. 0–100, per page and per component, and one number for the branch. 100 means the branch matches the target pixel for pixel and token for token. Verify also says which differences come from this branch and which do not, so "only your changes moved" is the answer you look for. The score is a fact, not a gate. Verify is on Team. The score is measured in pixels: the share of each page that matches the target, averaged over the pages. A colour change on a few elements is 99.
  6. Merge. A small confirm on the branch page, with the tag. Merge is open once there are no conflicts; on Team it also waits for a verify run. If main changed the same property since the branch started, that is a conflict: the Conflicts tab shows both sides and the person picks one.
  7. Sync. When anything is merged to main, every open branch syncs at once, with nobody pressing anything. See Sync and conflicts below.
  8. Tag. A name on a version of main, such as v1.4. Tags are what Versions lists. Every page, component, token and icon also has its own history, so "what did the pricing button look like at v1.2" has an answer.

Sync and conflicts

The rule is a three-way compare, property by property, between the last main the branch synced with, the new main, and the branch:

Main changed it Branch changed it Result
no — nothing to do
yes no the branch takes main's value, silently
no yes the branch keeps its value
yes, same value yes no conflict
yes, other value yes conflict
deleted it changed it (or the other way) conflict
  • A sync never stops for a conflict. The branch keeps its own value, the thing is marked with a red dot (branch menu, layers, Delta), and the owner is told. Everything else from main arrives.
  • Property, not object. Main changing a button's radius and the branch changing its label is two clean changes, not a conflict.
  • A conflict is settled once: keep this branch, take main, or edit it by hand. A settled conflict is not raised again by the next sync.
  • A branch with an open conflict cannot be merged. Merge shows each one.
  • Verify goes stale after a sync and runs again on its own, so the score on the menu is always against the current main.

The branch page

One page per branch, like a pull request, and the only place a branch is verified, settled and merged.

  • Header: the name, its status (ready to merge, 1 conflict), the owner, where it started, and what it does. Edit on this branch, and Merge to main.
  • Checks: Synced with main · Conflicts · Verify. Each is a way into its tab. Merge is greyed with the reason beside it until the checks allow it.
  • Tabs: Changes (main beside the branch, change by change) · Verify (the target, the verdict, page by page, and what differs) · Conflicts (each one with Keep this branch / Take main).
  • Merge opens a confirm over the page: what is going in, the tag and its note, and which branches will sync after.
  • Someone who can edit but not merge sees the same page with Merge greyed and who can merge; the free month sees Verify locked.

The ref is in the address

Every editor address names what it shows, after the product: main, a branch or a tag, always written — /chitragupt/web/main/journey, /chitragupt/web/kpi-empty-state/pages/<id>, /chitragupt/web/v1.4/pages/<id>. Every link in the editor keeps it, so moving between screens never drops you back on main. Editing on a branch writes to your draft on that branch, and its Review saves into that branch. A tag, and a merged or closed branch, open in View only. One picker in the top bar lists your draft, main, the open branches and the tags; picking one swaps only the ref. See 2026-10-21-ref-in-the-path.

Two modes of a ref

  • Complete — main with the ref's changes and your draft on top. What the product will look like after the merge. The default.
  • Delta — only what this ref and your draft change from main, on Pages, Components and Styles (?view=delta). The panel lists the changed pages, components, tokens and icons; the canvas shows only changed pages. A changed thing has a dot in both modes.

Why it matters

  • Main is always something someone approved.
  • Verify turns "does this still look like our product?" into a number.

Implications

  • A branch belongs to the person who made it. Others can view it.
  • The free month has 2 open branches at a time; a draft does not count. See plans.
  • AI changes always go to the draft, never to main. See ai-mode.
  • A merged or closed branch is kept, read-only, in Versions.
  • Branches and tags live in the top bar, in one picker on the left, with See all branches, All versions and Compare. The default is main, view only.
  • Compare works across anything: main, a tag, your draft, any open branch, for a page, component, icon or token.
  • A draft syncs with main like a branch does.

Vocabulary

Main · Draft · Review · Branch · Sync · Complete · Delta · Verify · Target · Consistency score · Conflict · Merge · Tag · Version. No synonyms ("fork", "pull request", "release") on any screen.

Related

Sources

  • The owner's instructions in the sessions of 2026-10-14 and 2026-10-16.