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