# 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](https://semver.org/): `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`
```bash
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

```python
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

```json
{
  "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

```tsx
<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

```tsx
<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)

```tsx
// 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

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

#### ✅ 8. README.md
**File**: `/opt/media-downloader/README.md`
**Lines**: 3 and 186

```markdown
**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:

```json
[
  {
    "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):

```markdown
## [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:

```bash
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:
```bash
/opt/media-downloader/scripts/update-all-versions.sh 11.26.3
```

---

## Post-Update Steps

### ✅ 11. Rebuild Frontend (if needed)
```bash
cd /opt/media-downloader/web/frontend
npm run build
```

### ✅ 12. Restart Services
```bash
sudo systemctl restart media-downloader-api
# Vite dev server will hot-reload automatically
```

### ✅ 13. Create Version Backup
```bash
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:

```bash
#!/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:

```bash
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)