# mojoPortal Update System — Quick Reference

**Version:** 1.0.0-alpha | **Update Framework:** SQM_Update_nnn.ps1 | **Status:** Ready

---

## Version Mapping Cheat Sheet

### Quick Lookup

| Version | Ordinal | Script | Status |
|---------|---------|--------|--------|
| 1.0.0 | 100 | SQM_Update_100.ps1 | ✅ Released |
| 1.0.1 | 101 | SQM_Update_101.ps1 | 📋 Planned |
| 1.0.2 | 102 | SQM_Update_102.ps1 | 📋 Planned |
| 1.0.5 | 105 | SQM_Update_105.ps1 | 📋 Future |
| 1.1.0 | 110 | SQM_Update_110.ps1 | 📋 Future |
| 1.2.0 | 120 | SQM_Update_120.ps1 | 📋 Future |
| 2.0.0 | 200 | SQM_Update_200.ps1 | 📋 Future |

### Calculation
```
Major.Minor.Patch → (Major × 100) + (Minor × 10) + Patch

1.0.0 → (1×100) + (0×10) + 0 = 100 ✓
1.2.3 → (1×100) + (2×10) + 3 = 123 ✓
2.5.7 → (2×100) + (5×10) + 7 = 257 ✓
```

---

## Common Commands

### Apply Latest Update (with backup)
```powershell
cd C:\___Work\SqliteMojo\Updates
.\SQM_Update_100.ps1
```

### Preview Update (dry run)
```powershell
.\SQM_Update_100.ps1 -DryRun
```

### Apply Without Backup (⚠️ risky)
```powershell
.\SQM_Update_100.ps1 -SkipBackup
```

### Check Current Version
```powershell
Get-Content "C:\___Work\SqliteMojo\VERSION.md" | Select-String "Version"
```

### View Update History
```powershell
Get-Content "C:\___Work\SqliteMojo\VERSION_HISTORY.md" | head -50
```

### List Available Backups
```powershell
Get-ChildItem "C:\___Work\SqliteMojo\Backups" -Directory | Sort-Object Name -Descending
```

### Restore from Backup
```powershell
$BackupDir = "C:\___Work\SqliteMojo\Backups\2024-01-15_v100"
Copy-Item "$BackupDir\*" -Destination "C:\___Work\SqliteMojo" -Recurse -Force
```

---

## When to Use Each Update Type

### Patch Updates (e.g., 1.0.0 → 1.0.1)
**Use when:**
- Bug fixes
- Security patches
- Minor improvements
- No breaking changes
- No new features

**Script:** `SQM_Update_101.ps1`

### Minor Updates (e.g., 1.0.0 → 1.1.0)
**Use when:**
- New features added
- Backward compatible
- Optional enhancements
- No major architecture changes

**Script:** `SQM_Update_110.ps1`

### Major Updates (e.g., 1.0.0 → 2.0.0)
**Use when:**
- Breaking changes
- Architecture redesign
- Major version leap
- Significant rewrites

**Script:** `SQM_Update_200.ps1`

---

## File Locations

```
C:\___Work\SqliteMojo\
├── Updates/
│   ├── SQM_Update_100.ps1         ← Current version script
│   ├── CHANGELOG_100.md            ← What changed
│   └── ...
├── Backups/
│   ├── 2024-01-15_v100/           ← Automatic backup
│   ├── 2024-01-20_v101/           ← Future backup
│   └── ...
├── VERSION.md                      ← Current version
├── VERSION_HISTORY.md              ← Update log
├── UPDATE_METHODOLOGY.md           ← How the system works
└── README.md, DEPLOYMENT.md, etc.
```

---

## Backup Strategy

### Automatic Backups
✅ Created before each update  
✅ Named with timestamp: `YYYY-MM-DD_vnnn`  
✅ Contains full source tree  
✅ Kept for 30 days  

### Manual Backup
```powershell
$Date = Get-Date -Format "yyyy-MM-dd"
$Version = "100"
$BackupDir = "C:\___Work\SqliteMojo\Backups\$Date`_v$Version-manual"

Copy-Item -Path "C:\___Work\SqliteMojo\*" `
    -Destination $BackupDir -Recurse -Force
```

### Backup Cleanup
```powershell
# Remove backups older than 30 days
Get-ChildItem "C:\___Work\SqliteMojo\Backups" -Directory | 
    Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-30)} | 
    Remove-Item -Recurse -Force
```

---

## Troubleshooting Quick Fixes

### "Script requires Administrator"
**Solution:** Right-click PowerShell → "Run as Administrator"

### "File not found" error
**Solution:** Verify path `C:\___Work\SqliteMojo` exists

### "Backup failed" error
**Solution:** Check disk space (need 2× source size)

### Update partially applied
**Solution:** Restore from backup and retry

### Can't rollback
**Solution:** Backups at `C:\___Work\SqliteMojo\Backups\` — restore manually

---

## Creating New Update Scripts

### Step 1: Copy Template
```powershell
Copy-Item ".\Updates\SQM_Update_100.ps1" ".\Updates\SQM_Update_101.ps1"
```

### Step 2: Update Version Numbers
```powershell
# In SQM_Update_101.ps1, change:
$CurrentVersion = "1.0.1"      # NEW version
$UpdateName = "SQM_Update_101"
```

### Step 3: Add Changes
```powershell
# In Apply-UpdateChanges function, add:
Write-Substep "Applying specific fixes"
# Copy files, update configs, etc.
Write-Success "Changes applied"
```

### Step 4: Create Changelog
```
# CHANGELOG_101.md
## Version 1.0.1

### Bug Fixes
- Fixed issue X
- Resolved problem Y

### Files Changed
- mojoPortal.Data.SQLite\SomeFile.cs
- Web\Admin\SomePage.aspx
```

### Step 5: Test
```powershell
# Dry run first
.\Updates\SQM_Update_101.ps1 -DryRun

# Then apply
.\Updates\SQM_Update_101.ps1
```

---

## Version Semantics

### What Each Part Means

**MAJOR (first digit)** — Breaking changes
```
1.0.0 → 2.0.0   (You may need to reconfigure)
```

**MINOR (second digit)** — New features (backward compatible)
```
1.0.0 → 1.1.0   (New features, but old stuff still works)
```

**PATCH (third digit)** — Bug fixes only
```
1.0.0 → 1.0.1   (Just fixes, no new features)
```

---

## Monitoring Updates

### Quick Status Check
```powershell
# Current version
$Ver = Get-Content "VERSION.md" | Select-String "Version:" | ForEach-Object {$_.ToString().Split(' ')[-1]}
Write-Host "Current Version: $Ver"

# Last update
$LastBackup = Get-ChildItem ".\Backups" | Sort-Object Name -Descending | Select-Object -First 1
Write-Host "Last Update: $($LastBackup.Name)"
```

### Scheduled Check
```powershell
# PowerShell scheduled task
$Action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "C:\check-version.ps1"
$Trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Monday -At 9am
Register-ScheduledTask -Action $Action -Trigger $Trigger -TaskName "CheckMojoPortalVersion"
```

---

## Documentation Files

| File | Purpose | When to Read |
|------|---------|--------------|
| `UPDATE_METHODOLOGY.md` | How the system works | Before first update |
| `VERSION_HISTORY.md` | What changed when | Before applying update |
| `SQM_Update_nnn.ps1` | Specific update script | When applying update |
| `CHANGELOG_nnn.md` | Detailed changes | Reviewing what's new |
| `README.md` | Project overview | Getting started |
| `DEPLOYMENT.md` | Server setup | First deployment |

---

## Emergency Procedures

### Quick Rollback (1 minute)
```powershell
# Find the most recent backup
$LastBackup = Get-ChildItem ".\Backups" | Sort-Object Name -Descending | Select-Object -First 1

# Restore everything
Copy-Item "$($LastBackup.FullName)\*" -Destination "." -Recurse -Force

# Verify
Get-Content "VERSION.md" | Select-String "Version"
```

### Complete Data Recovery
```powershell
# Find specific version backup
$Backup = Get-ChildItem ".\Backups" | Where-Object {$_.Name -like "*v100*"} | Select-Object -First 1

# Archive current broken state (for investigation)
Rename-Item -Path "." -NewName "BrokenState_$(Get-Date -Format 'yyyy-MM-dd')"

# Restore from backup
Copy-Item "$($Backup.FullName)\*" -Destination "." -Recurse -Force
```

---

## Best Practices Checklist

- ✅ Always use dry-run first: `-DryRun`
- ✅ Always backup before updates (unless you use automated backup)
- ✅ Test updates in dev before production
- ✅ Keep VERSION_HISTORY.md current
- ✅ Create CHANGELOG for each version
- ✅ Update documentation after changes
- ✅ Test rollback procedures
- ✅ Keep backups for 30+ days
- ✅ Document breaking changes clearly
- ✅ Notify stakeholders before major updates

---

## Example Update Sequence

### Current: v1.0.0 → Target: v1.0.2 (with intermediate v1.0.1)

**Step 1: Apply v1.0.1**
```powershell
.\Updates\SQM_Update_101.ps1
```

**Step 2: Verify v1.0.1**
```powershell
Get-Content "VERSION.md" | Select-String "Version"
# Should show: 1.0.1 ✓
```

**Step 3: Apply v1.0.2**
```powershell
.\Updates\SQM_Update_102.ps1
```

**Step 4: Verify v1.0.2**
```powershell
Get-Content "VERSION.md" | Select-String "Version"
# Should show: 1.0.2 ✓
```

**Result:** 1.0.0 → 1.0.1 → 1.0.2 ✅

---

## Quick Decision Tree

```
Do you want to apply an update?
├─ Yes, but preview first? → Use -DryRun flag
├─ Yes, and backup first? → Normal execution (recommended)
├─ Yes, skip backup? → Use -SkipBackup (dangerous!)
├─ No, but rollback? → Restore from Backups/ folder
└─ No, just check? → Read VERSION_HISTORY.md
```

---

**mojoPortal Update System — Ready for Production** ✅

For detailed information, see: `UPDATE_METHODOLOGY.md`  
For version history, see: `VERSION_HISTORY.md`  
For deployment, see: `DEPLOYMENT.md`