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