Skip to content

Merges

Data Layers

This document describes some internal stuff related to branches merging for better understanding how to work with this feature.

Internally branches logic works with low level entities: templates, their params, entities, their params, sprites. In UI you work with abstractions on top of this layer.

Branch Flags

We track all changes (like Git does) and use them during the merge.

Merge works on Layers 1-2

Merge logic works on Layer 1 and Layer 2. That means that for Balancy for some complex structures there are no direct connection, and we treat them as separate independent changes.

All changes are being tracked by items' internal IDs. So even though visually some changes could look the same, internally system treats them as different items.

Problematic cases

Common places to be aware of:

  1. Templates params.
  2. Lists of components.
  3. Layer 3 items.

Templates and their params

If you add the same parameter into the same template in different branches, for Balancy they are different, because internally they have different IDs.

  1. In branch-1 the parameter Count was added to template Item.
  2. In branch-2 the parameter Count was added to template Item.
  3. Merge branch-1 into branch-2.
  4. As a result, template Item will have two parameters named Count, visually identical in UI.

Do structural modifications in one branch

Adding/updating/deleting already existing parameters/templates would be better to do in one branch and then propagate these changes using merge mechanism.

Lists of documents

During the merge of document's Lists you cannot combine changes from both branches.

  1. In both branch-1 and branch-2 you have a list of In-Game Store pages: Page 1, Page 2.
  2. In branch-1 you have added Page 3.
  3. In branch-2 you have added Super Page.
  4. Merge branch-1 into branch-2.
  5. You will have to choose which branch to take changes from — branch-1 or branch-2.
  6. As a result, you will be able to get [Page 1, Page 2, Page 3] OR [Page 1, Page 2, Super Page] after conflict resolving.

Make change in document's List in one branch only

For now, we'd recommend to make changes in document's Lists in one branch and then merge into another.

We are planning to provide possibility to change the final resulting List during conflicts resolving. ETA: middle of December, 2024.

Layer 3 items

Let's take the example from the section about the Lists above. Together with changes in the List, you could have changes in Page 1 in branch-1 branch. And even if you choose branch-2 branch as a target and get final List as it is there, the changes in Page 1 from branch-1 will be merged anyway. Because for differences we always take changes from source branch.

We are planning to add additional Layer 3 on top of the current logic to treat some entities as a complex instead of separate independent documents.

Two examples are the following.

A/B Tests

A/B Test itself is a top level abstraction and operates with items from Layers 1 and 2. It has conditions and overrides. Condition is an item from Layer 2: documents and their params.

During the merge we work on Layer 2 and check changes on documents and their params level.

Let's say:

  1. Both branch-1 and branch-2 branches have an A/B Test with some conditions and overrides.
  2. Change override one in branch-1 branch.
  3. Add new override (override two) to the list in branch-1 branch.
  4. Delete one override from the list in branch-2 branch.
  5. Try to merge branch-1 into branch-2. There will be a conflict.
  6. If you choose target branch, branch-2, you will get:
    1. Resulted array as it was in branch-2 before merge (override deletion from branch-1 will not be merged).
    2. But changes in override one from branch-1 will be merged into branch-2 as well. Because on this level there is no conflict, only difference, which is taken from source branch.

That is the issue with all complex nested templates. Merge works with templates and their documents, it doesn't know that these components are the part of a higher level items (e. g. A/B Test).

Scripts

Script has a lot of connections between nodes and ports. If you make changes in the same script in different branches, it could lead to problems during the merge.

  1. Both branch-1 and branch-2 branches have a Script with several nodes.
  2. In branch-1 you have added new node (Node 3) between Node 1 and Node 2.
  3. In branch-2 you did the same: added new node (Node 3) between Node 1 and Node 2. These entities will get another IDs.
  4. During the merge there will be a lot of conflicts in ports and nodes.
  5. Doesn't matter how you are going to resolve the conflict, merge will lead into inconsistent state with node duplications and broken ports connections.

Don't change the same Script in multiple branches

For now, we'd recommend to do structural changes (new nodes, connections) in scripts in one branch only and then merge into another. If you just change values inside the node, it should be safe, because it doesn't involve entities creation.