media-downloader/docs/VERSION_UPDATE_CHECKLIST.md

Version Update Checklist

This document provides a comprehensive checklist for updating version numbers across the entire Media Downloader application.

⚠️ CRITICAL: Always follow this checklist when releasing a new version

---

Pre-Release Checklist

1. Determine Version Number

Follow Semantic Versioning: MAJOR.MINOR.PATCH

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

Current Version Format: 11.x.x

---

Version Update Locations

Core Version Files (REQUIRED)

✅ 1. /opt/media-downloader/VERSION

echo "X.X.X" > /opt/media-downloader/VERSION

• Single line with version number
• No v prefix
• Example: 11.26.2

✅ 2. Backend API Version

File: /opt/media-downloader/web/backend/api.py Line: ~266

app = FastAPI(
    title="Media Downloader API",
    description="Web API for managing media downloads from Instagram, TikTok, Snapchat, and Forums",
    version="X.X.X",  # ← UPDATE THIS
    lifespan=lifespan
)

✅ 3. Frontend Package Version

File: /opt/media-downloader/web/frontend/package.json Line: 4

{
  "name": "media-downloader-ui",
  "private": true,
  "version": "X.X.X",  // ← UPDATE THIS
  "type": "module",

✅ 4. Frontend App - Desktop Menu

File: /opt/media-downloader/web/frontend/src/App.tsx Line: ~192

<div className="border-t border-slate-200 dark:border-slate-700 px-4 py-2 mt-1">
  <p className="text-xs text-slate-500 dark:text-slate-400">vX.X.X</p>  {/* ← UPDATE THIS */}
</div>

✅ 5. Frontend App - Mobile Menu

File: /opt/media-downloader/web/frontend/src/App.tsx Line: ~305

<p className="px-3 py-1 text-xs text-slate-500 dark:text-slate-400">vX.X.X</p>  {/* ← UPDATE THIS */}

✅ 6. Configuration Page - About Tab

File: /opt/media-downloader/web/frontend/src/pages/Configuration.tsx Lines: ~2373 (comment) and ~2388 (version display)

// When creating a new version:
// 1. Update the version number below (currently vX.X.X)  ← UPDATE COMMENT

function AboutTab() {
  return (
    // ...
    <p className="text-slate-600 dark:text-slate-400 mb-1">Version X.X.X</p>  {/* ← UPDATE THIS */}

✅ 7. Install Script

File: /opt/media-downloader/scripts/install.sh Line: ~6

VERSION="X.X.X"  # ← UPDATE THIS

✅ 8. README.md

File: /opt/media-downloader/README.md Lines: 3 and 186

**Version:** X.X.X

├── VERSION                       # Version number (X.X.X)

---

Documentation Updates (REQUIRED)

✅ 9. Changelog JSON

File: /opt/media-downloader/data/changelog.json

Add new entry at the top of the array:

[
  {
    "version": "X.X.X",
    "date": "YYYY-MM-DD",
    "title": "Brief Release Title",
    "type": "major|minor|patch",
    "changes": [
      "🐛 FIXED: Description",
      "✨ ADDED: Description",
      "🗑️ REMOVED: Description",
      "🧹 CLEANED: Description",
      "📦 VERSION: Updated to X.X.X across all components"
    ],
    "fixes": [
      "List of bug fixes"
    ],
    "breaking_changes": [
      "List any breaking changes (optional)"
    ]
  },
  // ... previous versions
]

Emoji Guide:

• 🐛 Bug fixes
• ✨ New features
• 🗑️ Removed features
• 🧹 Code cleanup
• 🔒 Security updates
• 📦 Version updates
• ⚡ Performance improvements
• 📝 Documentation updates

✅ 10. CHANGELOG.md

File: /opt/media-downloader/CHANGELOG.md

Add new section at the top of the file (after header):

## [X.X.X] - YYYY-MM-DD

### 🎉 Release Title

#### Category 1
- **Description of change**
  - Detail 1
  - Detail 2

#### Category 2
- **Description of change**
  - More details

---

## [Previous Version] - Date

---

Quick Update Script

Use this one-liner to see all version references:

cd /opt/media-downloader && \
grep -rn "11\.26\." \
  VERSION \
  README.md \
  web/backend/api.py \
  web/frontend/package.json \
  web/frontend/src/App.tsx \
  web/frontend/src/pages/Configuration.tsx \
  data/changelog.json \
  CHANGELOG.md \
  scripts/install.sh \
  2>/dev/null | grep -v node_modules

Or use the automated script:

/opt/media-downloader/scripts/update-all-versions.sh 11.26.3

---

Post-Update Steps

✅ 11. Rebuild Frontend (if needed)

cd /opt/media-downloader/web/frontend
npm run build

✅ 12. Restart Services

sudo systemctl restart media-downloader-api
# Vite dev server will hot-reload automatically

✅ 13. Create Version Backup

cd /opt/media-downloader
bash scripts/create-version-backup.sh

This creates a locked backup with the version name for recovery purposes.

---

Verification Checklist

After updating all version numbers, verify:

• /opt/media-downloader/VERSION file shows correct version
• Backend API /api/docs shows correct version in OpenAPI spec
• Frontend desktop menu shows correct version (bottom of sidebar)
• Frontend mobile menu shows correct version (bottom of menu)
• Configuration → About tab shows correct version
• data/changelog.json has new entry at top
• CHANGELOG.md has new section at top
• Version backup created successfully
• All services restarted successfully
• Health page loads without errors
• No console errors in browser

---

Common Mistakes to Avoid

❌ Don't forget the v prefix in frontend displays (e.g., v11.26.2, not 11.26.2) ❌ Don't skip the package.json - npm scripts may depend on it ❌ Don't forget both locations in App.tsx - desktop AND mobile menus ❌ Don't forget to update the comment in Configuration.tsx - helps with future updates ❌ Don't add changelog entries to the bottom - always add to the top ❌ Don't forget to create a version backup - critical for rollback

---

Automated Version Update Script

You can use this helper script to update most version files automatically:

#!/bin/bash
# Usage: bash scripts/update-version.sh 11.26.3

NEW_VERSION="$1"

if [ -z "$NEW_VERSION" ]; then
    echo "Usage: $0 <version>"
    echo "Example: $0 11.26.3"
    exit 1
fi

echo "Updating to version $NEW_VERSION..."

# 1. Update VERSION file
echo "$NEW_VERSION" > /opt/media-downloader/VERSION

# 2. Update backend API
sed -i "s/version=\"[0-9]\+\.[0-9]\+\.[0-9]\+\"/version=\"$NEW_VERSION\"/" \
    /opt/media-downloader/web/backend/api.py

# 3. Update package.json
sed -i "s/\"version\": \"[0-9]\+\.[0-9]\+\.[0-9]\+\"/\"version\": \"$NEW_VERSION\"/" \
    /opt/media-downloader/web/frontend/package.json

# 4. Update App.tsx (both locations)
sed -i "s/>v[0-9]\+\.[0-9]\+\.[0-9]\+</>v$NEW_VERSION</g" \
    /opt/media-downloader/web/frontend/src/App.tsx

# 5. Update Configuration.tsx
sed -i "s/Version [0-9]\+\.[0-9]\+\.[0-9]\+/Version $NEW_VERSION/" \
    /opt/media-downloader/web/frontend/src/pages/Configuration.tsx
sed -i "s/currently v[0-9]\+\.[0-9]\+\.[0-9]\+/currently v$NEW_VERSION/" \
    /opt/media-downloader/web/frontend/src/pages/Configuration.tsx

echo "✓ Version updated to $NEW_VERSION in all files"
echo ""
echo "⚠️  Don't forget to manually update:"
echo "  - data/changelog.json (add new entry)"
echo "  - CHANGELOG.md (add new section)"
echo ""
echo "Then run: bash scripts/create-version-backup.sh"

Save this script as /opt/media-downloader/scripts/update-version.sh and make it executable:

chmod +x /opt/media-downloader/scripts/update-version.sh

---

Release Workflow Summary

1. Determine version number (MAJOR.MINOR.PATCH)
2. Run update script: bash scripts/update-all-versions.sh X.X.X
3. Update changelog.json (manual)
4. Update CHANGELOG.md (manual)
5. Update README.md if needed (manual)
6. Verify all locations (use grep command above)
7. Restart services: sudo systemctl restart media-downloader-api
8. Create version backup: bash scripts/create-version-backup.sh
9. Test application: Check Health page, About tab, and core functionality

---

Questions or Issues?

If you encounter any issues with version updates:

1. Check this document first
2. Verify all files using the grep command
3. Check git history for previous version updates
4. Review /opt/media-downloader/CHANGELOG.md for patterns

---

Last Updated: 2026-01-10 (v11.26.2)