media-downloader/docs/archive/VERSION_UPDATE_SUMMARY.md

# Version Update System - Summary

**Created**: 2025-10-31 (v6.4.2)
**Purpose**: Centralized system for managing version numbers across the application

---

## 📦 New Files Created

### 1. Quick Reference Guide
**File**: `/opt/media-downloader/VERSION_UPDATE.md`
- Fast track instructions (5 minutes)
- Links to full documentation
- Located in root for easy access

### 2. Complete Checklist
**File**: `/opt/media-downloader/docs/VERSION_UPDATE_CHECKLIST.md`
- Comprehensive step-by-step guide
- All 8 version locations documented
- Verification procedures
- Common mistakes to avoid
- Troubleshooting section

### 3. Automated Update Script
**File**: `/opt/media-downloader/scripts/update-version.sh`
- Updates 5 files automatically
- Validates version format
- Verifies all changes
- Interactive confirmation
- Color-coded output

### 4. README.md Updates
**File**: `/opt/media-downloader/README.md`
- Added "Version Updates" section
- Organized documentation links
- Updated to v6.4.2

---

## 📍 Version Storage Locations

### Automated by Script (5 files)
✅ `/opt/media-downloader/VERSION`
✅ `web/backend/api.py` (FastAPI version, line ~266)
✅ `web/frontend/package.json` (npm version, line 4)
✅ `web/frontend/src/App.tsx` (UI menus, lines ~192 & ~305)
✅ `web/frontend/src/pages/Configuration.tsx` (About tab, lines ~2373 & ~2388)

### Manual Updates Required (3 files)
❌ `data/changelog.json` - Add new version entry at top
❌ `CHANGELOG.md` - Add new version section at top
❌ `README.md` - Update version in header (line 3)

---

## 🚀 Usage Example

### Step 1: Run Automated Script
```bash
cd /opt/media-downloader
bash scripts/update-version.sh 6.5.0
```

**Output**:
- Updates 5 files automatically
- Verifies all changes
- Shows what needs manual updates

### Step 2: Manual Updates
```bash
# Edit changelog files
nano data/changelog.json    # Add entry at TOP
nano CHANGELOG.md          # Add section at TOP
nano README.md             # Update line 3
```

### Step 3: Restart & Backup
```bash
# Restart API
sudo systemctl restart media-downloader-api

# Create version backup
bash scripts/create-version-backup.sh
```

### Step 4: Verify
```bash
# Check all version references
grep -rn "6\.5\.0" VERSION web/backend/api.py web/frontend/package.json \
  web/frontend/src/App.tsx web/frontend/src/pages/Configuration.tsx \
  data/changelog.json CHANGELOG.md README.md 2>/dev/null | grep -v node_modules

# Open browser and check:
# - Configuration → About tab
# - Desktop/mobile menu version
# - Health page loads correctly
```

---

## 🎯 Design Goals

1. **Simplicity**: One command updates most files
2. **Safety**: Validation and verification built-in
3. **Documentation**: Clear instructions at multiple detail levels
4. **Consistency**: All version numbers updated together
5. **Traceability**: Clear audit trail of what was updated

---

## 📊 Version Number Format

Uses [Semantic Versioning](https://semver.org/): `MAJOR.MINOR.PATCH`

**Examples**:
- `7.0.0` - Major version with breaking changes
- `6.5.0` - Minor version with new features
- `6.4.3` - Patch version with bug fixes

**Current**: `6.4.2`

---

## 🔍 Quick Verification Command

Check all version references in one command:

```bash
cd /opt/media-downloader
grep -rn "$(cat VERSION)" \
  VERSION \
  web/backend/api.py \
  web/frontend/package.json \
  web/frontend/src/App.tsx \
  web/frontend/src/pages/Configuration.tsx \
  data/changelog.json \
  CHANGELOG.md \
  README.md \
  2>/dev/null | grep -v node_modules
```

Should show 8+ matches across all key files.

---

## 📚 Documentation Hierarchy

```
Quick Reference (5 min):
└── VERSION_UPDATE.md

Complete Guide (15 min):
└── docs/VERSION_UPDATE_CHECKLIST.md

Automated Tool:
└── scripts/update-version.sh

This Summary:
└── docs/VERSION_UPDATE_SUMMARY.md
```

---

## ✅ Success Criteria

After a version update, verify:

- [ ] All 8 files contain new version number
- [ ] No references to old version remain
- [ ] API service restarted successfully
- [ ] Frontend displays new version in 3 locations:
  - [ ] Desktop menu (bottom of sidebar)
  - [ ] Mobile menu (bottom)
  - [ ] Configuration → About tab
- [ ] Health page loads without errors
- [ ] Version backup created successfully
- [ ] No console errors in browser

---

## 🛠️ Maintenance

### Adding New Version Locations

If version appears in a new file:

1. **Update Documentation**:
   - `docs/VERSION_UPDATE_CHECKLIST.md` - Add to checklist
   - `VERSION_UPDATE.md` - Note if critical

2. **Update Script**:
   - `scripts/update-version.sh` - Add sed command
   - Add verification check

3. **Update This Summary**:
   - Add to "Version Storage Locations"

### Script Improvements

Located in: `/opt/media-downloader/scripts/update-version.sh`

Current features:
- Version format validation
- Interactive confirmation
- Automated updates (5 files)
- Verification checks
- Color-coded output

Future enhancements:
- Automatic changelog.json update
- Automatic CHANGELOG.md template
- README.md header auto-update
- Git commit creation option
- Rollback capability

---

## 📝 Notes

- **Created during**: v6.4.2 release
- **Motivation**: Prevent version number inconsistencies
- **Files**: 8 locations across Python, TypeScript, JSON, and Markdown
- **Time saved**: ~10 minutes per release
- **Errors prevented**: Missing version updates in UI/API

---

**Last Updated**: 2025-10-31 (v6.4.2)