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.

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. Packages installation.
3. Lists of components.
4. 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.

Packages installation/update

It's a common situation, when developer wants to update package in the current branch. But meanwhile another team member could update the same package in another branch. And if you try to merge these branches, there could be problems.

As mentioned earlier, comparisons are made by items internal IDs. So even though package update could add the same template param into both branches, during the merge we will treat them as a different items, because they will receive different IDs when being added.

For example:

1. In branch-1 branch you updated the package. Integer parameter Count was added to template Item, being assigned with ID 1001.
2. In branch-2 branch you updated the same package. Integer parameter Count was added to template Item, too, but being assigned with ID 1002.
3. Merge branch-1 into branch-2.
4. As a result, template Item will have two parameters Count, with IDs 1001 and 1002.

The same for templates, sprites or other items, which were added during the merge.

Update package in one branch

For now, we'd recommend to install/update packages in one specific branch, dedicated for that. And merge it from time to time into any other branches, when needed, to prevent such duplication issues.

We are researching the ways to make it possible to update package in different branches without an issues on merge.

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.