# Versioning & Artifact Storage Strategy

## Version Format

Tekton Armageddon uses semantic versioning: `MAJOR.MINOR.PATCH`

- **MAJOR**: Breaking changes, incompatible API changes
- **MINOR**: New features, backward-compatible
- **PATCH**: Bug fixes, content updates, backward-compatible

Current version source: `project.godot` → `config/version`

## Artifact Types

### 1. Patch PCK Files
- **Purpose**: Hot-patch content updates without full client reinstall
- **Storage**: GitHub Actions artifacts (90 days) + tekton-updates repo
- **Naming**: `patch.pck` (latest), versioned in tekton-updates repo
- **Integrity**: SHA256 checksums generated and stored alongside

### 2. Platform Builds
- **Platforms**: Windows, Linux, Android
- **Storage**: GitHub Actions artifacts (90 days) + GitHub Releases (permanent)
- **Naming**: `tekton_armageddon_{Platform}_v{VERSION}.{ext}`
- **Trigger**: Git tags (`v*.*.*`) or manual workflow dispatch
- **Integrity**: SHA256 checksums for each platform build

### 3. Version Manifest
- **File**: `assets/data/version.json`
- **Purpose**: Client version checking, changelog delivery, patch URLs
- **Storage**: Embedded in builds + tekton-updates repo
- **Integrity**: SHA256 checksum

## Workflows

### Patch Deployment (`deploy_patch.yml`)
**Trigger**: Push to `patch-release` branch or manual dispatch

**Process**:
1. Auto-bump patch version from `project.godot`
2. Extract changelog from `CHANGELOG_DRAFT.md` [NEXT] section
3. Generate `version.json` with new release entry
4. Commit version bump back to repo
5. Build `patch.pck` from changed files
6. Generate SHA256 checksums
7. Upload artifacts to GitHub Actions (90-day retention)
8. Push to `tekton-updates` public repo (`latest/` folder)

**Artifacts**:
- `patch-pck-{SHA}`: patch.pck + checksum
- `version-manifest-{SHA}`: version.json + checksum

### Platform Builds (`build_artifacts.yml`)
**Trigger**: Git tag push (`v*.*.*`) or manual dispatch with version input

**Process**:
1. Matrix build for Windows, Linux, Android
2. Export using Godot export presets
3. Generate SHA256 checksums per platform
4. Upload artifacts to GitHub Actions (90-day retention)
5. Create GitHub Release with all platform builds + checksums

**Artifacts**:
- `tekton-{Platform}-v{VERSION}`: platform binary + checksum

## Artifact Retention

| Artifact Type | Storage Location | Retention | Purpose |
|--------------|------------------|-----------|---------|
| Patch PCK | GitHub Actions | 90 days | CI/CD history, rollback |
| Patch PCK | tekton-updates repo | Permanent | Client downloads |
| Platform Builds | GitHub Actions | 90 days | CI/CD history |
| Platform Builds | GitHub Releases | Permanent | Distribution |
| Version Manifest | tekton-updates repo | Permanent | Client version checks |

## Checksum Verification

All artifacts include SHA256 checksums for integrity verification:

```bash
# Verify patch.pck
sha256sum -c patch.pck.sha256

# Verify platform build
sha256sum -c tekton_armageddon_Windows_v2.3.8.sha256
```

## Version Compatibility

`version.json` includes `minimum_app_version` field:
- Clients below this version must reinstall full build
- Clients at or above can use patch system

## Changelog Management

**Source**: `CHANGELOG_DRAFT.md`

**Format**:
```markdown
## [NEXT]
- Feature or fix description
- Another change

## [2.3.7] — 2026-05-15
- Archived release notes
```

**Process**:
1. Developers add entries under `[NEXT]`
2. CI extracts `[NEXT]` entries on patch deployment
3. CI archives to versioned section
4. CI clears `[NEXT]` for next cycle

## Manual Version Bump

For local testing without CI:

```bash
# Update versions but keep changelog
python3 tools/generate_version_json.py --local

# Skip changelog update entirely
python3 tools/generate_version_json.py --skip-changelog
```

## Release Process

### Patch Release
1. Merge changes to `patch-release` branch
2. CI auto-bumps version, builds, deploys
3. Clients auto-download on next launch

### Full Release
1. Tag commit: `git tag v2.4.0`
2. Push tag: `git push origin v2.4.0`
3. CI builds all platforms, creates GitHub Release
4. Distribute via Steam, Google Play, etc.

## Rollback Strategy

**Patch Rollback**:
1. Locate previous patch in GitHub Actions artifacts or tekton-updates repo
2. Manually push to `tekton-updates/latest/`
3. Update `version.json` to point to previous version

**Full Build Rollback**:
1. Download previous release from GitHub Releases
2. Re-tag or create hotfix branch
3. Redeploy via standard release process

## Future Enhancements

- [ ] Automated rollback on failed health checks
- [ ] Delta patching for bandwidth optimization
- [ ] Multi-region CDN distribution
- [ ] Staged rollout (canary deployments)
- [ ] Automated compatibility testing matrix