Initial commit

skills/references/unity-guide.md

@@ -0,0 +1,140 @@
+# Unity Project Version Management
+
+## Overview
+
+Unity projects use a dual-file approach for version management:
+1. **`version.json`** - Single source of truth (easy to read/edit)
+2. **`ProjectSettings/ProjectSettings.asset`** - Auto-synced (used by Unity builds)
+
+## File Structure
+
+```
+MyUnityProject/
+├── version.json                          # Primary source
+├── ProjectSettings/
+│   └── ProjectSettings.asset            # Auto-synced
+└── Assets/
+    └── ...
+```
+
+## version.json (Primary)
+
+Create this file at project root:
+
+```json
+{
+  "version": "1.2.3",
+  "buildNumber": 42,
+  "releaseDate": "2025-10-20"
+}
+```
+
+**Fields:**
+- `version` (required): Semantic version (MAJOR.MINOR.PATCH)
+- `buildNumber` (optional): Incremental build number
+- `releaseDate` (optional): Release date in YYYY-MM-DD format
+
+## ProjectSettings.asset (Auto-sync)
+
+The `bundleVersion` field in this file is automatically synced from `version.json`:
+
+```yaml
+PlayerSettings:
+  bundleVersion: 1.2.3
+  AndroidBundleVersionCode: 42
+  buildNumber:
+    iOS: 42
+```
+
+## Workflow
+
+### Manual Update
+
+1. Edit `version.json`:
+   ```json
+   {
+     "version": "1.3.0"
+   }
+   ```
+
+2. Run sync script:
+   ```bash
+   python scripts/sync_unity_version.py
+   ```
+
+3. Commit both files:
+   ```bash
+   git add version.json ProjectSettings/ProjectSettings.asset
+   git commit -m "chore: bump version to 1.3.0"
+   ```
+
+### Automatic Update (with auto-release-manager)
+
+The skill handles everything automatically:
+
+```
+1. Update version.json → 1.3.0
+2. Sync to ProjectSettings.asset
+3. Git commit both files
+4. Create tag v1.3.0
+5. Push to remote
+```
+
+## Benefits of Dual-File Approach
+
+✅ **Easy Version Management**
+- `version.json` is simple JSON, easy to read/edit
+- Clean git diffs
+
+✅ **Unity Integration**
+- `ProjectSettings.asset` is used by Unity builds
+- Version automatically appears in build
+
+✅ **Automated Sync**
+- Scripts ensure consistency
+- No manual errors
+
+✅ **Extended Metadata**
+- `version.json` can store additional info (buildNumber, releaseDate)
+- `ProjectSettings.asset` only has bundleVersion
+
+## Common Issues
+
+### Q: Why not just use ProjectSettings.asset?
+
+A: ProjectSettings.asset is a YAML file that's hard to read and edit manually. It also contains hundreds of other settings, making git diffs noisy.
+
+### Q: Can I use only version.json?
+
+A: No. Unity reads bundleVersion from ProjectSettings.asset for builds. Both files are needed.
+
+### Q: What if files get out of sync?
+
+A: Run `python scripts/sync_unity_version.py` to sync from version.json (source of truth) to ProjectSettings.asset.
+
+## Example: Version Update
+
+**Before:**
+```json
+// version.json
+{
+  "version": "1.2.3",
+  "buildNumber": 42
+}
+```
+
+**After:**
+```json
+// version.json
+{
+  "version": "1.3.0",
+  "buildNumber": 43
+}
+```
+
+**Auto-synced:**
+```yaml
+# ProjectSettings.asset
+PlayerSettings:
+  bundleVersion: 1.3.0  # ← Automatically updated
+```