Merge conflicts when working in "hybrid" branches

[MonikaBarget]

Some of the information below should also be integrated into the user tutorials, depending on the updates you may want to make to the game-creation workflow.

Problem descriptions

Demo games must remain intact

Most user repos are hybrid workspaces where Games contains both dev demo/test games and user-created unique games. As I have tested before, removing demo games from your branch will cause too many issues when getting upstream updates as upstream expects deleted files even when they are not needed locally and also not technically necessary for testing. Upstream will constantly ask you to confirm that the missing files are missing on purpose.

Renaming demo games is not allowed

Similar issues occur when users do not create new games in addition to demo games but rename existing demos and develop them further. This happened with my extended map game, for which I used the initial map demo folder. Git will always flag it as an issue that a) the game got renamed, and that b) the renamed game folder contains new files which the upstream naturally does not have. This is seemingly a challenge that many tech teams face, including the Palantir developers, who wrote about it on Medium:

We had a case where one team lost huge amounts of time, slowing down their work for months, due to the difficulty of backporting patches after a refactoring that involved a lot of renames. This resulted in them calling a meeting where they requested an agreement to never refactor the code ever again; it was a rather suboptimal state of affairs that could have been avoided with a better merge capability.

Copying demo games or the game template with intact relationships causes merge issues

Making a direct copy of a demo game or game template with the "cp" command or "npm run create-game" currently results in merge conflicts because Git knows that the files come from a shared source file. Git will constantly ask you to confirm edits to both the original file and its copy while the relationship remains intact.

What users should do

1. Upstream should continue to update all demo/test games, and users should keep merging them all, in addition to all engine updates.
2. User games have to be in newly created game folders that have unique names to avoid any potential overlaps with dev demos. Furthermore, users must make sure that their games are seen as independent files by Git and not treated as variants of the originals. This is why the cp -r command instead of cp should be used for making new games from templates with Git. -r means recursive. This command copies a directory and all its contents using the file system. Git only becomes aware of the new files when you git add them. In this way, Git does not record the copy operation. The new files are treated as untracked until you stage them, which can prevent merge issues, but if the content of the new files is identical or very similar to the original ones, Git’s rename/copy detection (-M/-C flags) may still recognize the new files as copies later.
3. A better long-term solution is to use .gitattributes to disable rename detection for specific files. The user's .gitattributes file should specify which folder to exclude:

foldername/ -merge=union
foldername/ -diff -merge

Potentially, this could also be applied to the entire src/Games folder by default, but users should be informed about potential risks either way.

4. The best solution, however, will be to disable rename detection globally when users make a new game with npm run create-game. This requires that the StoryScript engine ensures that no copying relationships are visible to Git.
5. If a game folder was already created by copying another game and uses experience merge conflicts, they should create a clean copy of their game folder, giving it a new name, and delete the previous copy after. Example:

cp -r src/Games/ImperialCirclesMap src/Games/ImperialCirclesMapMB
git add src/Games/ImperialCirclesMapMB
git commit -m "Add ImperialCirclesMapMB as independent game"

rm -rf src/Games/ImperialCirclesMap
git add -A src/Games/ImperialCirclesMap
git commit -m "Remove ImperialCirclesMap"

3. Users must only edit their src/Games/YourUniqueGameFolder/, and then commit their own folder using:

git add src/Games/YourUniqueGameFolder
git commit -m "Save work for my unique game"

5. Then they can update from upstream with a normal merge command (no hard reset or rebase needed):

git fetch upstream
git merge upstream/master

6. To be on the safe side, users can make a backup of their branch first and restore their game folder from a temporary backup:

cp -a /tmp/backup/YourUniqueGameFolder src/Games/
git add src/Games/YourUniqueGameFolder
git commit -m "Restore my game folder"

7. To be sure, users can verify that only their folder is different:

git diff --name-only origin/master -- . | grep -v '^src/Games/YourUniqueGameFolder/'

If that returns anything, they have unwanted deviations outside their unique game!

8. As a final step, users need to commit the new status and push!

[MonikaBarget]

I have updated the text above because no hard reset is needed once Git no longer treats new games as copies of demos / templates but as independent files. I had no problems merging upstream changes after creating a copy of my existing game folder with the cp -r command.