Skip to content

t1k:unity:base:theme-branch-sync

FieldValue
Modulebase
Version5.116.6
Effortlow
Tools—

Keywords: master-sexy-theme, merge master into theme, sexy theme, submodule theme, sync theme, theme branch

/t1k:unity:base:theme-branch-sync

Unity Theme Branch Sync — Permanent Theme Branch Maintenance

Section titled “Unity Theme Branch Sync — Permanent Theme Branch Maintenance”

A theme branch = latest master + visual re-skin only (sprites, audio, prefab skins). It is permanent: merged into, never replaced. Never create numbered generations.

SSOT: the runbook THEME_BRANCH.md at the root of the theme branch in the submodule repo (e.g. Assets/TheOneFeature.PuzzleUI/THEME_BRANCH.md). Read it first if present — it may be newer than this skill.

Sync routine (when master moves; at least weekly)

Section titled “Sync routine (when master moves; at least weekly)”
Terminal window
cd <submodule path> # e.g. Assets/TheOneFeature.PuzzleUI
git fetch origin
git checkout <theme-branch> && git pull # e.g. master-sexy-theme
git merge origin/master
git rev-list --count <theme-branch>..origin/master # MUST print 0
git push
cd <game root>
git add <submodule path>
git commit -m "chore(submodule): bump <name> <theme-branch>"
git push

master owns function, theme owns visuals.

  • Scripts, components, new nodes, structure → take master’s side (--theirs)
  • Sprites, colors, audio, pure skin files → take theme’s side (--ours)
  • Mixed prefab hunks → resolve by hand per the rule, verify the prefab opens in Unity
  • Enable git config rerere.enabled true once per machine — identical conflicts auto-resolve next time

Arrive unskinned — expected, not a bug. Designers reskin on the theme branch afterward (feat(theme): skin <Feature>). That is the ONLY kind of authored commit allowed on a theme branch.

Forbidden (violating any of these recreates the “gen-N” mess)

Section titled “Forbidden (violating any of these recreates the “gen-N” mess)”
NeverWhy
Create a new generation branch (-2, -5, gen-N)The branch is permanent; merge into it
Rebase / force-push the theme branchGames pin it as a submodule
Commit functional changes on the theme branchFunction belongs on master (cherry-pick)
Merge theme → mastermaster must stay theme-free
Let syncs pile up for monthsSmall regular merges keep conflicts trivial

Post-merge QA (MANDATORY — run before every push)

Section titled “Post-merge QA (MANDATORY — run before every push)”

A merge is not done when git says “Merge made”. It is done when all of these pass:

Terminal window
# 0. Confirm you are on the theme branch — master must never receive theme commits
git branch --show-current # must print the theme branch name
# 1. No leftover conflict markers anywhere
git diff --check
grep -rn "<<<<<<<" --include="*.prefab" --include="*.asset" --include="*.unity" . ; # must be empty
# 2. Theme delta contains ZERO code files (theme = visuals only)
git diff --name-only origin/master...HEAD | grep -E '\.(cs|asmdef|asmref)$' # must be EMPTY
# 3. Master is untouched: local/remote master unchanged by this work
git rev-list --count origin/master..master 2>/dev/null # 0 or branch absent

Then in the Unity editor of a consuming game:

  1. Let it compile — Console must show 0 errors (missing APIs, broken refs).
  2. Open the themed prefabs that the merge touched — no Missing Script, no missing sprite/audio references.
  3. Play-mode smoke test: home screen, shop, win popup, lose flow, and any NEW feature screens the merge brought in.
  4. Roll out canary-style: bump the submodule pin in one game first, let its CI build pass, then roll to other games.

Only after 0–7 pass: git push.

  • This workflow must NEVER modify master of the submodule: no pushes, no merges into it, no tags moved. All commits land on the theme branch only.
  • If a functional fix is discovered during QA, commit it to a branch off master (PR to master), then merge master back into the theme branch — never fix function directly on theme.
Terminal window
git rev-list --count <theme-branch>..origin/master # 0 = fully synced
git diff --name-only origin/master...<theme-branch> # exact theme delta
  • Repo The1Studio/TheOneFeature.PuzzleUI, branch master-sexy-theme. Legacy *-sexy* branches are frozen for old games — never delete or rebase them.

Branch provenance (creation date, archived predecessor tag): references/known-instances.md.

  • Any .md (or other asset) added inside Assets/ of the submodule needs its Unity-generated .meta committed too, or every consumer’s working tree goes dirty.
  • After deleting a remote branch, other machines still see it until git fetch --prune.
  • Long-term exit strategy: migrate the theme to Unity Prefab Variants inside master, then retire the theme branch entirely.