Branching on MetaCroc Docs

Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Concepts #

This page explains how branches work internally. UI actions are described on the other pages in this section.

Branch and system scope #

A branch is a named, independently evolving copy of the metadata model inside one system. All branches share the same element identities; each branch keeps its own versions.

Every system has exactly one main branch. Existing systems were migrated so that all their history belongs to main.
main cannot be renamed or deleted.
Branches form an unlimited hierarchy: each non-main branch has a source (parent) branch.
The branch you work in is chosen in the project tree (see Editing on a branch).

Baseline version per element #

When a branch is created, MetaCroc records for every element of the source branch which version the new branch starts from. This is the element’s baseline on the branch. No metadata is copied.

Branches

Mon, 01 Jan 0001 00:00:00 +0000

Branches #

Open Branches from the activity bar. The page works on the system selected in the project tree; without a system it shows Select a system to view branches.

Branch tree #

The left panel shows Branch tree with a search field (Search branches…, filters by name) and filter pills:

Filter	Shows
Opened	Active branches (default together with Locked)
Locked	Locked branches (default)
Archived	Archived branches
Deleted	Deleted branches
Protected	Only protected branches

Default view in a system you open for the first time:

Editing on a branch

Mon, 01 Jan 0001 00:00:00 +0000

Editing on a branch #

Choose the working branch #

The project tree header contains the Branch selector next to the system selector. Options are all branches of the system that are not deleted.

Selecting a branch:

reloads the project tree from that branch
makes element detail, edit, push, versions, dependencies, validation, and search work on that branch
keeps a separate set of open tabs per system and branch

The choice is remembered per system in the browser. Set as active on the Branches page does the same. The branch is not part of the URL, so a shared link opens in the recipient’s own active branch.

Compare and diff

Mon, 01 Jan 0001 00:00:00 +0000

Compare and diff #

Compare shows which elements differ between two branches and lets you drill down to field-level changes. The same comparison drives merge requests, rebase, and cherry-pick.

Where to compare #

Branch detail → Compare tab: Compare with defaults to the parent branch. For main, select a branch first.
Context menu → Compare with…: dialog Compare branch (Comparing {branch} against), then the same comparison view.
Merge request detail: affected structures with their diff (see Merge requests).
Versions tab: compare two versions of one element on the active branch.

Any branch of the system except deleted ones can be selected.

Merge requests

Mon, 01 Jan 0001 00:00:00 +0000

Merge requests #

A merge request (MR) proposes applying the changes of a source branch onto a target branch. It collects approvals, holds conflict resolutions, and is merged with an explicit Merge action.

Lifecycle #

stateDiagram-v2 direction LR state "Changes requested" as ChangesRequested state "In review" as Review { [*] --> Open [*] --> Approved: 0 approvals, no conflicts Open --> Approved: Quorum reached Approved --> Open: Required approvals raised Open --> ChangesRequested: Request changes ChangesRequested --> Open: Mark as open Open --> Stale: Marked stale (API) Stale --> Open: Diff recalculated } [*] --> Review: Create MR Review --> Merged: Merge (Approved only) Review --> Rejected: Reject Review --> Closed: Close MR (author)

Rebase and cherry-pick

Mon, 01 Jan 0001 00:00:00 +0000

Rebase and cherry-pick #

Two ways to bring changes onto a branch without a merge request. Both are performed directly by the user, need no approval, and are written to the audit log.

Rebase from parent #

A branch starts from the parent’s versions at creation time and does not see later parent pushes (see Concepts). Rebase from parent moves the branch onto the parent’s current state and keeps the branch’s own changes on top.

Permissions

Mon, 01 Jan 0001 00:00:00 +0000

Permissions #

Branching uses the existing MetaCroc access management (ACL on systems and elements). There are no separate branch roles yet.

What applies today #

Area	Rule
List branches	VIEW permission on the system
View, edit, push, lock elements on a branch	Element ACL (VIEW, EDIT, FORCE UNLOCK), same as without branches
Lock, unlock, archive, restore, protect, delete a branch (UI)	Administrator or user with the create system permission (Admin actions require the Project Admin role.)
Create branch, edit branch, rebase, compare, cherry-pick, create MR	Any user who can see the system
Approve, request changes, reject an MR	Any user except the author (unless self-approval is allowed); one vote per user
Merge an approved MR	Any user who can see the MR
Close or reopen an MR	Author
Cherry-pick	VIEW on the target system and on each transferred element
Change Minimum number of approvers	Editing the system (Overview)

Protected branches #

A protected branch accepts changes only through merged merge requests:

Releases and deployment

Mon, 01 Jan 0001 00:00:00 +0000

Releases and deployment #

With branching, every deployment package belongs to exactly one branch. Packages pin a specific version of each element, so scripts are generated from a known state of that branch.

Deployment Packages page #

Open Deployment Packages from the activity bar. The page lists packages of the selected system with columns Package, Branch, Status, Responsible user.

New package #

New package opens New deployment package:

Team workflow

Mon, 01 Jan 0001 00:00:00 +0000

Team workflow #

A reference process for parallel teams built on the implemented features: branches, protected branches, merge requests, rebase, cherry-pick, and branch-bound deployment packages. Adapt branch names to your tenant.

Branch layout #

flowchart TB mainNode["main / PROD"] preprod["preprod / PREPROD"] devA["dev-a / DEV-A"] devB["dev-b / DEV-B"] featA1["feature/A-1"] featB1["feature/B-1"] hotfix["hotfix/..."] mainNode --> preprod preprod --> devA preprod --> devB devA --> featA1 devB --> featB1 mainNode --> hotfix

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

Glossary #

Term	Definition
Active branch	The branch selected in the project tree; all element operations use it. Shown with the Active tag.
Baseline	Version of an element a branch started from (parent’s version at creation or after the last rebase). Common ancestor for three-way comparison.
Branch	Named, independently evolving copy of the metadata model inside one system.
Branch status	Active (Opened), Locked, Archived, Deleted.
Branch tree	Hierarchy of branches on the Branches page.
Cherry-pick	Copy selected elements from another branch into the current branch as new versions.
Compare	List of elements changed between two branches with field-level diff.
Confidential branch	Branch with restrict to explicit permissions; currently enforced only for cherry-pick sources.
Conflict	Same field changed differently on both branches since the baseline.
Deployment package	Set of elements with pinned versions for script generation and deployment; belongs to one branch.
Main branch	The `main` branch of a system; cannot be renamed or deleted.
Merge	Applying an approved merge request to the target branch.
Merge event	Audit record of an executed merge.
Merge lock	Lock on the target branch held while a merge runs, when require explicit merge action is set.
Merge request (MR)	Reviewable proposal to merge a source branch into a target branch.
Minimum number of approvers	System parameter (0–10, default 0); lower bound for required approvals of new or edited branches.
Own version	Latest version of an element pushed on the branch itself.
Opened	UI label of the Active status; also the default tree filter (Active + Locked).
Protected branch	Branch that accepts changes only through merge requests.
Quorum	Number of approvals needed: the target branch’s Required approvals.
Rebase from parent	Move a branch’s baselines to the parent’s current state while keeping own changes.
Required approvals	Approvals needed for merge requests into the branch; 0 approves conflict-free MRs immediately.
Self-approval	Whether the MR author may approve their own MR.
Source branch	Parent of a branch; also the branch that brings changes in an MR or cherry-pick.
Stale	MR status meaning the diff is outdated and approvals must be collected again.
Version label	`{branch-name}-{number}`, for example `main-12`.
Working data	Edit draft of an element, stored per branch.