Skip to content

Work / Trunk / Wiki / Decisions

2026-10-21-ref-in-the-path

Decisioncanonicalverified 2026-10-21

DECISION.2026-10-21.REF-IN-THE-PATH

The branch is in the path

Asked for and approved by the owner on 2026-10-21.

Decision

Every editor address names what it shows: main, a branch or a tag. It is the segment after the product, always written, main too.

/chitragupt/web                           → /chitragupt/web/main/journey
/chitragupt/web/<ref>/journey
/chitragupt/web/<ref>/pages/<id>
/chitragupt/web/<ref>/components/<id>
/chitragupt/web/<ref>/styles/<group>/<id>
/chitragupt/web/<ref>/analysis
/chitragupt/web/<ref>/review              your draft on that ref
/chitragupt/web/<branch>/branch           checks, Verify, Conflicts, Merge

/chitragupt/web/branches                  all branches
/chitragupt/web/versions                  all tags
/chitragupt/web/compare
/chitragupt/web/preview
  • <ref> is main, a branch or a tag. Main and an open branch open in View or Edit. A tag, and a merged or closed branch, open in View only: Edit is locked, and review and branch are not there for a tag.
  • Editing on a branch writes to your draft on that branch. Review saves it into that branch. Your draft on main and your draft on a branch are two drafts; each syncs with its own ref.
  • Every link inside the editor keeps the ref, the way it keeps ?mode=edit. Moving from Pages to Components on kpi-empty-state stays on kpi-empty-state.
  • One picker in the top bar lists your draft, main, the open branches and the tags. Picking one keeps the screen and swaps only the ref. It replaces the Versions menu; All versions and Compare move into it.
  • Delta works on any ref, on Pages, Components and Styles: ?view=delta shows only what that ref and your draft on it change from main. Complete stays the default.
  • Names cannot collide. A branch cannot be named branches, versions, compare or preview, nor take a tag's name; a tag cannot take a branch's name. main is already taken by main. A tag name is lower case letters, numbers, dots and dashes, so it is safe in an address. These are checks in the migration, so the schema changes and is shown to the owner first.
  • No new tables. @trunk/history already takes a ref for drafts, sync, Review and values. Only the web app is held to main today.

Why

The owner, 2026-10-21: the branch is not in the address, so changing page always goes back to main, and a branch has no Delta. The editor read main in every loader, and "Edit on this branch" opened Pages on main.

A path segment, not a query: the owner asked for domain/company/product/branch/.... It reads like a repository address, and a link to a page on a branch is the whole state.

Main is always written, so there is one shape of address and every link is built the same way.

Considered and not done:

  • ?ref=branch:name. Shorter to build, but the owner wants the branch in the path.
  • Leaving main out. Two shapes of address, and every branch name would have to avoid every section name.
  • Tags only on the Versions page. A tag is a fixed point people link to; opening it in the editor answers "what did it look like at v1.2".

Impact

  • branch-verify-merge: the ref in the address, Delta on any ref, the picker.
  • CLAUDE.md: the URL scheme.
  • Surfaces: branch-menu becomes the ref picker; pages-delta, pages-on-branch, versions, version-detail and branch change; Delta is drawn on Components and Styles.
  • The schema: the name checks above.
  • The app: every editor route moves under [ref]; the branch page moves from branches/<name> to <name>/branch.
  • Feature: features/0022-ref-in-the-path.md.

Status

Active

Sources