t1k:unity:base:theme-branch-sync
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
Keywords: master-sexy-theme, merge master into theme, sexy theme, submodule theme, sync theme, theme branch
How to invoke
Section titled “How to invoke”/t1k:unity:base:theme-branch-syncUnity 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)”cd <submodule path> # e.g. Assets/TheOneFeature.PuzzleUIgit fetch origingit checkout <theme-branch> && git pull # e.g. master-sexy-themegit merge origin/mastergit rev-list --count <theme-branch>..origin/master # MUST print 0git pushcd <game root>git add <submodule path>git commit -m "chore(submodule): bump <name> <theme-branch>"git pushConflict rule (the only rule)
Section titled “Conflict rule (the only rule)”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 trueonce per machine — identical conflicts auto-resolve next time
New features from master
Section titled “New features from master”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)”| Never | Why |
|---|---|
Create a new generation branch (-2, -5, gen-N) | The branch is permanent; merge into it |
| Rebase / force-push the theme branch | Games pin it as a submodule |
| Commit functional changes on the theme branch | Function belongs on master (cherry-pick) |
| Merge theme → master | master must stay theme-free |
| Let syncs pile up for months | Small 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:
# 0. Confirm you are on the theme branch — master must never receive theme commitsgit branch --show-current # must print the theme branch name
# 1. No leftover conflict markers anywheregit diff --checkgrep -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 workgit rev-list --count origin/master..master 2>/dev/null # 0 or branch absentThen in the Unity editor of a consuming game:
- Let it compile — Console must show 0 errors (missing APIs, broken refs).
- Open the themed prefabs that the merge touched — no Missing Script, no missing sprite/audio references.
- Play-mode smoke test: home screen, shop, win popup, lose flow, and any NEW feature screens the merge brought in.
- 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.
Master safety
Section titled “Master safety”- This workflow must NEVER modify
masterof 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.
Health check / inspection
Section titled “Health check / inspection”git rev-list --count <theme-branch>..origin/master # 0 = fully syncedgit diff --name-only origin/master...<theme-branch> # exact theme deltaKnown instance
Section titled “Known instance”- Repo
The1Studio/TheOneFeature.PuzzleUI, branchmaster-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.
Hard rules
Section titled “Hard rules”- Any
.md(or other asset) added insideAssets/of the submodule needs its Unity-generated.metacommitted 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.