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

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

# 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

# Restart API
sudo systemctl restart media-downloader-api

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

Step 4: Verify

# 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: 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:

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)