141 lines
2.9 KiB
Markdown
141 lines
2.9 KiB
Markdown
# 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
|
|
```
|