Todd
338
docs/VERSION_UPDATE_CHECKLIST.md
Normal file
338
docs/VERSION_UPDATE_CHECKLIST.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user