Add merge handoff document with copy-pasteable commands
Complete handoff guide for merging feature/api-keys-refactor: - Pre-merge verification steps - Exact merge commands (copy & paste ready) - Post-merge testing checklist - Links to all documentation - Rollback procedures - Release notes template All systems verified and ready for merge.
This commit is contained in:
vicrodh committed
1 parent
34ab753524
commit
59e7562af0
1 file changed
+427
@@ -0,0 +1,427 @@
|
|||||||
|
# 🚀 HANDOFF: API Keys Refactor - Ready to Merge
|
||||||
|
|
||||||
|
**Date:** January 17, 2026
|
||||||
|
**Branch:** `feature/api-keys-refactor`
|
||||||
|
**Status:** ✅ Ready for merge to `main`
|
||||||
|
**Working Tree:** Clean (verified)
|
||||||
|
**Commits:** 13 commits ahead of main
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Pre-Merge Verification
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Verify current location
|
||||||
|
pwd
|
||||||
|
# Should be: /home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor
|
||||||
|
|
||||||
|
# Verify branch
|
||||||
|
git branch
|
||||||
|
# Should show: * feature/api-keys-refactor
|
||||||
|
|
||||||
|
# Verify clean state
|
||||||
|
git status
|
||||||
|
# Should show: nothing to commit, working tree clean
|
||||||
|
|
||||||
|
# Verify commits ready
|
||||||
|
git log --oneline origin/main..HEAD
|
||||||
|
# Should show 13 commits
|
||||||
|
```
|
||||||
|
|
||||||
|
**All checks passed:** ✅
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Commits to Merge (13 total)
|
||||||
|
|
||||||
|
```
|
||||||
|
34ab753 Add post-merge cleanup instructions for API Keys UI
|
||||||
|
7d07f9a Add merge preparation documentation
|
||||||
|
81b65bd Add comprehensive CHANGELOG for API keys refactor
|
||||||
|
80ba2bf Fix Discogs artwork selection UI issues
|
||||||
|
732a489 Improve Discogs artwork selection with multi-release images
|
||||||
|
279d433 Add catalog number support for precise Discogs searches
|
||||||
|
2a5c181 Fix Discogs artwork selection to show unique images
|
||||||
|
dab5c28 Add Discogs artwork selection UI in album edit modal
|
||||||
|
dd70f0a Refactor Discogs integration to use Cloudflare Workers proxy
|
||||||
|
9099123 Refactor Spotify and Tidal playlist import to use proxy
|
||||||
|
179a6b7 Refactor Last.fm integration to use Cloudflare Workers proxy
|
||||||
|
3a49e3f Remove embedded Last.fm API secret for Flathub compliance
|
||||||
|
b7048fa feat: register qbz:// URI scheme for OAuth callbacks
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Merge Commands (Copy & Paste)
|
||||||
|
|
||||||
|
### Step 1: Ensure you're in the main worktree
|
||||||
|
```bash
|
||||||
|
cd /home/blitzkriegfc/Personal/qbz/qbz-nix
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Ensure main is up to date
|
||||||
|
```bash
|
||||||
|
git checkout main
|
||||||
|
git pull origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Merge feature branch (no fast-forward for clean history)
|
||||||
|
```bash
|
||||||
|
git merge --no-ff feature/api-keys-refactor -m "Merge feature/api-keys-refactor: Remove embedded API keys and add Discogs artwork selector
|
||||||
|
|
||||||
|
This major refactor achieves Flathub compliance by removing all embedded
|
||||||
|
API credentials from the binary. All API requests now go through a
|
||||||
|
Cloudflare Workers proxy for secure credential management.
|
||||||
|
|
||||||
|
New Features:
|
||||||
|
- Discogs artwork selection UI with multi-release support
|
||||||
|
- Catalog number support for audiophile libraries
|
||||||
|
- Carousel navigation for artwork options
|
||||||
|
- Release metadata display (title, year)
|
||||||
|
|
||||||
|
Technical Changes:
|
||||||
|
- Cloudflare Workers proxy for Last.fm, Spotify, Tidal, Discogs
|
||||||
|
- Database migration adds catalog_number column
|
||||||
|
- URI scheme registration (qbz://) for OAuth flows
|
||||||
|
- Rate limiting and User-Agent validation server-side
|
||||||
|
|
||||||
|
See CHANGELOG-api-keys-refactor.md for complete details.
|
||||||
|
See POST-MERGE-CLEANUP.md for removing legacy API Keys UI."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Resolve conflicts (if any)
|
||||||
|
```bash
|
||||||
|
# If conflicts occur (likely in SettingsView.svelte due to audio config changes)
|
||||||
|
git status
|
||||||
|
# Check which files have conflicts
|
||||||
|
|
||||||
|
# For each conflicted file:
|
||||||
|
# 1. Open in editor
|
||||||
|
# 2. Look for <<<<<<< HEAD markers
|
||||||
|
# 3. Keep BOTH changes (main's audio config + feature's other changes)
|
||||||
|
# 4. Remove conflict markers
|
||||||
|
# 5. git add <file>
|
||||||
|
|
||||||
|
# After resolving all conflicts:
|
||||||
|
git merge --continue
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Push to origin
|
||||||
|
```bash
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Tag the release
|
||||||
|
```bash
|
||||||
|
git tag -a v1.2.0 -m "API Keys Refactor - Flathub Compliance
|
||||||
|
|
||||||
|
Major changes:
|
||||||
|
- Removed all embedded API credentials
|
||||||
|
- Added Cloudflare Workers proxy for credential management
|
||||||
|
- Added Discogs artwork selection UI
|
||||||
|
- Added catalog number support
|
||||||
|
- Database migration for catalog_number column
|
||||||
|
- Flathub submission now possible"
|
||||||
|
|
||||||
|
git push origin v1.2.0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 7: Cleanup (optional - can keep branch for reference)
|
||||||
|
```bash
|
||||||
|
# Delete local feature branch (optional)
|
||||||
|
git branch -d feature/api-keys-refactor
|
||||||
|
|
||||||
|
# Delete remote feature branch (optional)
|
||||||
|
git push origin --delete feature/api-keys-refactor
|
||||||
|
|
||||||
|
# Remove worktree (optional)
|
||||||
|
git worktree remove /home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧪 Post-Merge Testing Checklist
|
||||||
|
|
||||||
|
### Critical Tests (Must Pass)
|
||||||
|
- [ ] App launches without errors
|
||||||
|
- [ ] Database migration runs (check logs for catalog_number column)
|
||||||
|
- [ ] Last.fm login works
|
||||||
|
- [ ] Last.fm scrobbling works
|
||||||
|
- [ ] Spotify playlist import works
|
||||||
|
- [ ] Tidal playlist import works
|
||||||
|
- [ ] Discogs artwork search works
|
||||||
|
- [ ] Discogs carousel navigation works (4+ images)
|
||||||
|
- [ ] Artwork save works (select image → Save)
|
||||||
|
- [ ] Settings view intact (audio config + other sections)
|
||||||
|
|
||||||
|
### Regression Tests (Should Still Work)
|
||||||
|
- [ ] Audio playback
|
||||||
|
- [ ] Local library scanning
|
||||||
|
- [ ] Album/Artist browsing
|
||||||
|
- [ ] Search functionality
|
||||||
|
- [ ] Playlist management
|
||||||
|
- [ ] Downloads
|
||||||
|
|
||||||
|
### Open browser DevTools and check console for:
|
||||||
|
- [ ] No errors on startup
|
||||||
|
- [ ] No errors when fetching Discogs artwork
|
||||||
|
- [ ] Logs show: "Downloading Discogs artwork from: ..."
|
||||||
|
- [ ] Logs show: "Downloaded to: ..."
|
||||||
|
- [ ] Logs show: "Set album artwork successfully"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 What Changed - Quick Summary
|
||||||
|
|
||||||
|
### 🔐 Security & Compliance
|
||||||
|
- ❌ Removed Last.fm API secret from binary
|
||||||
|
- ❌ Removed Spotify credentials from binary
|
||||||
|
- ❌ Removed Tidal credentials from binary
|
||||||
|
- ❌ Removed Discogs credentials from binary
|
||||||
|
- ✅ Cloudflare Workers proxy handles all credentials
|
||||||
|
- ✅ Flathub submission now possible
|
||||||
|
|
||||||
|
### ✨ New Features
|
||||||
|
1. **Discogs Artwork Selector**
|
||||||
|
- Visual UI in album edit modal
|
||||||
|
- Multi-release support (4 images from top 2 releases)
|
||||||
|
- Carousel navigation (4 per page)
|
||||||
|
- Shows release title and year
|
||||||
|
- Smart search (uses catalog number if available)
|
||||||
|
|
||||||
|
2. **Catalog Number Support**
|
||||||
|
- Reads from audio file tags (CATALOGNUMBER field)
|
||||||
|
- Stored in database
|
||||||
|
- Displayed in UI ("Cat# XXXXX")
|
||||||
|
- Prioritized in Discogs searches
|
||||||
|
|
||||||
|
### 🔧 Technical
|
||||||
|
- Cloudflare Workers proxy deployed: `https://qbz-api-proxy.blitzkriegfc.workers.dev`
|
||||||
|
- Database migration adds `catalog_number` column (automatic, non-destructive)
|
||||||
|
- URI scheme `qbz://` registered for OAuth
|
||||||
|
- ~715 lines of legacy code documented for removal (POST-MERGE-CLEANUP.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ Known Issues
|
||||||
|
|
||||||
|
### 1. Discogs 429 Rate Limits
|
||||||
|
- **Severity:** Low
|
||||||
|
- **Frequency:** Occasional (when fetching detailed release info)
|
||||||
|
- **Impact:** User must retry after a few seconds
|
||||||
|
- **Status:** Acceptable (transient error)
|
||||||
|
- **User Experience:** Works on retry
|
||||||
|
|
||||||
|
### 2. API Keys UI Still Visible
|
||||||
|
- **Why:** Legacy code, avoids conflicts with audio config changes
|
||||||
|
- **Status:** Documented for removal
|
||||||
|
- **Action:** Follow `POST-MERGE-CLEANUP.md` after merge
|
||||||
|
- **Note:** UI accepts input but credentials are ignored (all goes through proxy)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 Important Documentation Files
|
||||||
|
|
||||||
|
### 1. CHANGELOG-api-keys-refactor.md
|
||||||
|
**Location:** `/home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor/CHANGELOG-api-keys-refactor.md`
|
||||||
|
|
||||||
|
**Contains:**
|
||||||
|
- Complete list of all changes
|
||||||
|
- Security improvements details
|
||||||
|
- New features with user benefits
|
||||||
|
- Technical architecture changes
|
||||||
|
- Database migrations
|
||||||
|
- Testing notes
|
||||||
|
- Breaking changes (none for users)
|
||||||
|
- Deployment requirements
|
||||||
|
|
||||||
|
**Read this:** Before announcing release to users
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. MERGE-PREP.md
|
||||||
|
**Location:** `/home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor/MERGE-PREP.md`
|
||||||
|
|
||||||
|
**Contains:**
|
||||||
|
- Pre-merge checklist (all ✅)
|
||||||
|
- Merge strategy recommendations
|
||||||
|
- Post-merge testing plan
|
||||||
|
- Rollback procedures
|
||||||
|
- Release notes template
|
||||||
|
- Success criteria
|
||||||
|
|
||||||
|
**Read this:** Before doing the merge (you're reading the HANDOFF now, so this is optional)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. POST-MERGE-CLEANUP.md
|
||||||
|
**Location:** `/home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor/POST-MERGE-CLEANUP.md`
|
||||||
|
|
||||||
|
**Contains:**
|
||||||
|
- Step-by-step instructions to remove API Keys UI
|
||||||
|
- 11 files to modify with line numbers
|
||||||
|
- Before/after code examples
|
||||||
|
- Verification steps
|
||||||
|
- Git commit message template
|
||||||
|
- Estimated 30-45 minutes to complete
|
||||||
|
|
||||||
|
**Read this:** After merge, when ready to clean up legacy code
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌐 Cloudflare Workers Proxy
|
||||||
|
|
||||||
|
**Status:** ✅ Deployed and operational
|
||||||
|
**URL:** `https://qbz-api-proxy.blitzkriegfc.workers.dev`
|
||||||
|
**Repository:** `/home/blitzkriegfc/Personal/qbz/qbz-api-proxy`
|
||||||
|
|
||||||
|
**Endpoints Active:**
|
||||||
|
- Last.fm: `/lastfm/*`
|
||||||
|
- Spotify: `/spotify/token`, `/spotify/refresh`
|
||||||
|
- Tidal: `/tidal/token`, `/tidal/refresh`
|
||||||
|
- Discogs: `/discogs/search`, `/discogs/release/{id}`, `/discogs/image`
|
||||||
|
|
||||||
|
**Test Proxy:**
|
||||||
|
```bash
|
||||||
|
curl https://qbz-api-proxy.blitzkriegfc.workers.dev
|
||||||
|
# Should return: {"service":"QBZ API Proxy","version":"1.0.0",...}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎉 Release Notes Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## QBZ v1.2.0 - API Keys Refactor & Discogs Enhancement
|
||||||
|
|
||||||
|
### 🔐 Security & Flathub Compliance
|
||||||
|
We've completely removed all embedded API credentials from the application.
|
||||||
|
All API requests now go through a secure Cloudflare Workers proxy, making
|
||||||
|
QBZ ready for Flathub submission and improving overall security.
|
||||||
|
|
||||||
|
### ✨ New Features
|
||||||
|
|
||||||
|
**Discogs Artwork Selector**
|
||||||
|
Browse and select album artwork directly from Discogs! The new visual selector
|
||||||
|
shows multiple release variants with metadata, making it easy to find the
|
||||||
|
perfect cover for your albums.
|
||||||
|
|
||||||
|
- 🎨 Visual artwork browser in album edit modal
|
||||||
|
- 🖼️ See images from different release variants
|
||||||
|
- 📄 Navigate with carousel (4 images per page)
|
||||||
|
- 📋 View release titles and years
|
||||||
|
- 🏷️ Smart search using catalog numbers
|
||||||
|
|
||||||
|
**Catalog Number Support**
|
||||||
|
For audiophile and collector libraries with professional tagging:
|
||||||
|
- Automatically reads catalog numbers from audio file tags
|
||||||
|
- Displays in album details (e.g., "Cat# MFSL 1-395")
|
||||||
|
- Prioritized in Discogs searches for precise results
|
||||||
|
|
||||||
|
### 🔧 Technical Improvements
|
||||||
|
- Cloudflare Workers proxy for all external APIs
|
||||||
|
- Database migration adds catalog_number support
|
||||||
|
- Improved error handling and logging
|
||||||
|
- Rate limiting and validation server-side
|
||||||
|
|
||||||
|
### 🐛 Known Issues
|
||||||
|
- Occasional 429 rate limit errors from Discogs (retry after a few seconds)
|
||||||
|
|
||||||
|
### 🙏 Thanks
|
||||||
|
Special thanks to all users who requested catalog number support!
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Rollback Plan (If Needed)
|
||||||
|
|
||||||
|
If critical issues found after merge:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Find the merge commit
|
||||||
|
git log --oneline -10
|
||||||
|
|
||||||
|
# Revert the merge (safest option)
|
||||||
|
git revert -m 1 <merge-commit-hash>
|
||||||
|
git push origin main
|
||||||
|
|
||||||
|
# OR hard reset (use with EXTREME caution)
|
||||||
|
git reset --hard <commit-before-merge>
|
||||||
|
git push --force origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Support Checklist
|
||||||
|
|
||||||
|
If users report issues after release:
|
||||||
|
|
||||||
|
1. **Proxy Down**
|
||||||
|
- Check: https://qbz-api-proxy.blitzkriegfc.workers.dev
|
||||||
|
- Verify Cloudflare Workers dashboard
|
||||||
|
- Check environment variables are set
|
||||||
|
|
||||||
|
2. **Database Migration Failed**
|
||||||
|
- Check app logs for migration errors
|
||||||
|
- May need manual `ALTER TABLE local_tracks ADD COLUMN catalog_number TEXT;`
|
||||||
|
|
||||||
|
3. **API Integration Broken**
|
||||||
|
- Check proxy is responding
|
||||||
|
- Verify User-Agent is "QBZ/1.0.0"
|
||||||
|
- Check rate limits not exceeded
|
||||||
|
|
||||||
|
4. **UI Issues**
|
||||||
|
- Clear browser cache
|
||||||
|
- Check browser console for errors
|
||||||
|
- Verify Settings changes don't conflict with audio config
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Final Verification Before Merge
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# You are here
|
||||||
|
pwd
|
||||||
|
# → /home/blitzkriegfc/Personal/qbz/qbz-worktrees/feature-api-keys-refactor
|
||||||
|
|
||||||
|
# Branch is clean
|
||||||
|
git status
|
||||||
|
# → nothing to commit, working tree clean ✅
|
||||||
|
|
||||||
|
# All commits ready
|
||||||
|
git log --oneline origin/main..HEAD | wc -l
|
||||||
|
# → 13 ✅
|
||||||
|
|
||||||
|
# Proxy is up
|
||||||
|
curl -s https://qbz-api-proxy.blitzkriegfc.workers.dev | grep service
|
||||||
|
# → "service":"QBZ API Proxy" ✅
|
||||||
|
|
||||||
|
# Ready to merge!
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Next Steps After Merge
|
||||||
|
|
||||||
|
1. ✅ **Immediate:** Test all integrations (checklist above)
|
||||||
|
2. 📢 **Within 24h:** Announce release with release notes
|
||||||
|
3. 🧹 **When convenient:** Follow `POST-MERGE-CLEANUP.md` to remove API Keys UI
|
||||||
|
4. 🚀 **Future:** Submit to Flathub!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Notes
|
||||||
|
|
||||||
|
- Feature branch can be kept for reference or deleted
|
||||||
|
- Worktree can remain or be removed
|
||||||
|
- CHANGELOG files will be in main after merge
|
||||||
|
- No user data affected by this merge
|
||||||
|
- All changes are backward compatible
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Prepared by:** Claude Sonnet 4.5
|
||||||
|
**Handoff Date:** January 17, 2026
|
||||||
|
**Status:** ✅ READY TO MERGE
|
||||||
|
|
||||||
|
🚀 **You're all set! Just run the merge commands above.**
|
||||||
Reference in new issue
Block a user