# Migration Guide: v0.15 → v0.16
**From**: v0.15.x
**To**: v0.16.0
**Est. Time**: 15-30 minutes
**Last Updated**: October 5, 2025
---
## Overview
Gorev v0.16.0 introduces significant architectural changes. This guide helps you migrate from v0.15.x to v0.16.0 safely.
### Major Changes in v0.16.0
| Feature | v0.15.x | v0.16.0 | Impact |
|---------|---------|---------|--------|
| **Database** | Global `~/.gorev/gorev.db` | Per-workspace `.gorev/gorev.db` | High |
| **Web UI** | Not available | Embedded React UI | Medium |
| **NPM Package** | Various names | `@mehmetsenol/gorev-mcp-server` | Low |
| **Template Aliases** | Not available | `bug`, `feature`, etc. | Low |
| **REST API** | Not available | 23 endpoints (Fiber) | Medium |
| **VS Code Extension** | MCP protocol | REST API | Medium |
---
## Pre-Migration Checklist
### 1. Backup Everything
```bash
# Backup global database
cp ~/.gorev/gorev.db ~/gorev-v0.15-backup-$(date +%Y%m%d).db
# Export all tasks to JSON
gorev export --output ~/gorev-tasks-backup.json --include-all
# Backup config files
cp ~/.config/Claude/claude_desktop_config.json ~/claude-config-backup.json
```
### 2. Check Current Version
```bash
gorev --version
# Should show v0.15.x
```
### 3. Document Active Projects
```bash
# List all projects and their task counts
gorev project list > ~/projects-before-migration.txt
# Export per-project task lists
for project in $(gorev project list | grep "ID:" | awk '{print $2}'); do
gorev task list --project $project > ~/tasks-${project}.txt
done
```
---
## Migration Path
### Option 1: Clean Install (Recommended)
**Best for**: New users or those wanting fresh start
**Steps**:
1. **Uninstall v0.15**:
```bash
# Remove old binary
which gorev
rm /usr/local/bin/gorev # Or wherever it's installed
# Keep backup of old database
mv ~/.gorev ~/.gorev-v0.15-backup
```
2. **Install v0.16**:
```bash
npm install -g @mehmetsenol/gorev-mcp-server
```
3. **Initialize workspaces**:
```bash
# For each project
cd /path/to/project-a
gorev-mcp init
cd /path/to/project-b
gorev-mcp init
```
4. **Import data** (if needed):
```bash
cd /path/to/project-a
gorev-mcp import --input ~/gorev-tasks-backup.json --project-filter "Project A"
```
### Option 2: In-Place Upgrade
**Best for**: Existing users with many tasks
**Steps**:
1. **Install v0.16 alongside v0.15**:
```bash
npm install -g @mehmetsenol/gorev-mcp-server
# Old binary still at /usr/local/bin/gorev
# New binary at $(npm bin -g)/gorev-mcp
```
2. **Migrate data gradually**:
```bash
# Keep v0.15 running while migrating
# Initialize v0.16 workspaces
cd /path/to/project
gorev-mcp init
# Export from v0.15
gorev export --project "My Project" --output project-backup.json
# Import to v0.16
gorev-mcp import --input project-backup.json
```
3. **Verify migration**:
```bash
# Compare task counts
gorev task list --count # v0.15
gorev-mcp task list --count # v0.16
```
4. **Remove v0.15**:
```bash
# Once satisfied with v0.16
rm /usr/local/bin/gorev
rm -rf ~/.gorev-v0.15-backup # After 30 days
```
---
## Step-by-Step Migration
### Step 1: Database Migration (15 min)
#### 1.1 Export All Data
```bash
# Export everything from v0.15
gorev export \
--output ~/gorev-full-export.json \
--include-completed \
--include-dependencies \
--include-templates \
--include-ai-context
```
**Verify export**:
```bash
# Check file size (should be > 0)
ls -lh ~/gorev-full-export.json
# Count tasks in export
cat ~/gorev-full-export.json | jq '.tasks | length'
```
#### 1.2 Identify Projects
```bash
# List unique projects in export
cat ~/gorev-full-export.json | jq -r '.tasks[].project' | sort -u
# Example output:
# Backend API
# Frontend App
# Infrastructure
# Mobile App
```
#### 1.3 Create Workspace Per Project
```bash
# Create directory structure
mkdir -p ~/projects/{backend-api,frontend-app,infrastructure,mobile-app}
# Initialize each workspace
cd ~/projects/backend-api
gorev-mcp init --name "Backend API"
cd ~/projects/frontend-app
gorev-mcp init --name "Frontend App"
cd ~/projects/infrastructure
gorev-mcp init --name "Infrastructure"
cd ~/projects/mobile-app
gorev-mcp init --name "Mobile App"
```
#### 1.4 Import Data Per Workspace
```bash
# Filter and import tasks per project
cd ~/projects/backend-api
gorev-mcp import \
--input ~/gorev-full-export.json \
--project-filter "Backend API" \
--conflict-resolution skip
# Repeat for each workspace
```
### Step 2: Configuration Migration (5 min)
#### 2.1 Update Claude Desktop Config
**Old (v0.15)**:
```json
{
"mcpServers": {
"gorev": {
"command": "/usr/local/bin/gorev",
"args": ["serve"]
}
}
}
```
**New (v0.16)**:
```json
{
"mcpServers": {
"gorev": {
"command": "npx",
"args": ["-y", "@mehmetsenol/gorev-mcp-server", "serve"],
"env": {
"GOREV_LANG": "en"
}
}
}
}
```
#### 2.2 Update VS Code/Cursor Config
**Create workspace-specific config**:
```bash
# In each project directory
cd ~/projects/backend-api
mkdir -p .kilocode
cat > .kilocode/mcp.json << 'EOF'
{
"mcpServers": {
"gorev": {
"command": "npx",
"args": ["-y", "@mehmetsenol/gorev-mcp-server", "serve"],
"env": {
"GOREV_LANG": "en"
}
}
}
}
EOF
```
#### 2.3 Update Scripts and Automation
```bash
# Find all scripts using old gorev command
grep -r "gorev " ~/scripts/
# Update to use gorev-mcp or npx
sed -i 's/gorev /gorev-mcp /g' ~/scripts/my-script.sh
# Or use npx
sed -i 's/gorev /npx @mehmetsenol\/gorev-mcp-server /g' ~/scripts/my-script.sh
```
### Step 3: Verification (5 min)
#### 3.1 Verify Workspaces
```bash
# List all registered workspaces
gorev-mcp workspace list
# Expected output:
# backend-api (15 tasks)
# frontend-app (23 tasks)
# infrastructure (7 tasks)
# mobile-app (12 tasks
```
#### 3.2 Verify Task Counts
```bash
# Compare with pre-migration counts
cat ~/projects-before-migration.txt
# Check each workspace
cd ~/projects/backend-api && gorev-mcp task list --count
cd ~/projects/frontend-app && gorev-mcp task list --count
```
#### 3.3 Test Web UI
```bash
# Start server
gorev-mcp serve
# Open browser
open http://localhost:5082
# Verify:
# - Workspace switcher shows all workspaces
# - Tasks load correctly
# - Can create new task
# - Template system works
```
#### 3.4 Test MCP Integration
**In Claude Desktop**:
```
List all my workspaces
```
**Expected**: Claude lists all 4 workspaces
```
Show me tasks from the backend-api workspace
```
**Expected**: Claude shows tasks from that workspace
---
## Breaking Changes
### 1. Template Requirement (v0.10.0)
**Removed**: `gorev_olustur` MCP tool
**Migration**:
```bash
# Old way (no longer works)
gorev task create \
--title "Fix bug" \
--description "Some bug"
# New way (required)
gorev-mcp task create \
--template bug \
--field baslik="Fix bug" \
--field modul="backend" \
--field ortam="production"
```
### 2. Database Location
**Old**: `~/.gorev/gorev.db` (global)
**New**: `.gorev/gorev.db` (per workspace)
**Impact**:
- AI assistants need workspace context
- Can't share tasks between projects (by design)
- Need to export/import to move tasks
### 3. NPM Package Name
**Old**: Various unofficial packages
**New**: `@mehmetsenol/gorev-mcp-server`
**Migration**:
```bash
# Uninstall old packages
npm uninstall -g gorev
npm uninstall -g @mehmetsenol/gorev-mcp-server
npm uninstall -g gorev-mcp-server
# Install official package
npm install -g @mehmetsenol/gorev-mcp-server
```
### 4. VS Code Extension API
**Old**: MCP protocol over stdio
**New**: REST API over HTTP
**Impact**:
- Better performance
- No markdown parsing errors
- Automatic workspace detection
**Migration**: Update to Gorev VS Code extension v0.16.0+
---
## Troubleshooting Migration
### Tasks Missing After Import
**Check**:
```bash
# Verify import log
cat ~/.gorev/import.log
# Check conflict resolution
gorev-mcp import --input backup.json --dry-run
# Manual verification
sqlite3 .gorev/gorev.db "SELECT COUNT(*) FROM gorevler;"
```
**Fix**:
```bash
# Re-import with different conflict resolution
gorev-mcp import \
--input backup.json \
--conflict-resolution overwrite \
--force
```
### Workspace Not Detected
**Check**:
```bash
# Verify .gorev/ directory exists
ls -la .gorev/
# Check database file
ls -lh .gorev/gorev.db
# Verify workspace registered
gorev-mcp workspace list
```
**Fix**:
```bash
# Re-initialize if needed
mv .gorev .gorev-backup
gorev-mcp init
# Restore data
gorev-mcp import --input ../backup.json
```
### MCP Server Connection Issues
**Check**:
```bash
# Test server manually
gorev-mcp serve --debug
# Verify NPM package
which gorev-mcp
gorev-mcp --version
```
**Fix**:
```bash
# Reinstall package
npm uninstall -g @mehmetsenol/gorev-mcp-server
npm cache clean --force
npm install -g @mehmetsenol/gorev-mcp-server
# Update MCP configs (see Step 2.1)
```
### Template Errors After Migration
**Check**:
```bash
# List templates
gorev-mcp template list
# Verify default templates exist
sqlite3 .gorev/gorev.db "SELECT COUNT(*) FROM gorev_templateleri;"
# Should be 6
```
**Fix**:
```bash
# Reinitialize templates
sqlite3 .gorev/gorev.db < \
/path/to/gorev-mcpserver/internal/veri/migrations/002_default_templates.sql
```
---
## Rollback Plan
If migration fails, you can rollback:
### Rollback to v0.15
```bash
# 1. Uninstall v0.16
npm uninstall -g @mehmetsenol/gorev-mcp-server
# 2. Restore v0.15 binary
cp ~/gorev-v0.15-binary /usr/local/bin/gorev
chmod +x /usr/local/bin/gorev
# 3. Restore old database
rm -rf ~/.gorev
cp -r ~/.gorev-v0.15-backup ~/.gorev
# 4. Restore old configs
cp ~/claude-config-backup.json ~/.config/Claude/claude_desktop_config.json
# 5. Restart services
pkill gorev
gorev serve
```
### Verify Rollback
```bash
gorev --version # Should show v0.15.x
gorev task list # Should show your old tasks
```
---
## Post-Migration Tasks
### 1. Update Documentation
```bash
# Update team wiki/docs with new commands
# Old: gorev task create
# New: gorev-mcp task create --template <alias>
```
### 2. Update CI/CD Pipelines
```bash
# Update deployment scripts
# Use new NPM package
npm install -g @mehmetsenol/gorev-mcp-server
# Update task automation
npx @mehmetsenol/gorev-mcp-server task create --template bug ...
```
### 3. Train Team
- Share this migration guide
- Demo Web UI features
- Explain multi-workspace concept
- Show template aliases
### 4. Monitor for Issues
```bash
# Check logs for first week
gorev-mcp serve --debug 2>&1 | tee migration-monitoring.log
# Review daily
grep -i error migration-monitoring.log
grep -i warning migration-monitoring.log
```
---
## New Features to Explore
After migration, explore these v0.16.0 features:
### 1. Web UI
```bash
gorev-mcp serve
open http://localhost:5082
```
**Features**:
- Visual task management
- Multi-workspace switcher
- Template wizard
- Real-time updates
### 2. Template Aliases
```bash
# Use memorable aliases instead of UUIDs
gorev-mcp task create --template bug ...
gorev-mcp task create --template feature ...
gorev-mcp task create --template research ...
```
### 3. Multi-Workspace
```bash
# Switch contexts easily
cd /path/to/project-a
gorev-mcp task list # Shows project-a tasks
cd /path/to/project-b
gorev-mcp task list # Shows project-b tasks
```
### 4. REST API
```bash
# Direct API access
curl http://localhost:5082/api/tasks
curl http://localhost:5082/api/workspaces
```
---
## Migration Checklist
Use this checklist to track your progress:
- [ ] **Pre-Migration**
- [ ] Backup global database
- [ ] Export all tasks to JSON
- [ ] Backup config files
- [ ] Document active projects
- [ ] **Installation**
- [ ] Install v0.16 NPM package
- [ ] Verify installation
- [ ] Test basic commands
- [ ] **Data Migration**
- [ ] Create workspace directories
- [ ] Initialize each workspace
- [ ] Import data per workspace
- [ ] Verify task counts match
- [ ] **Configuration**
- [ ] Update Claude Desktop config
- [ ] Update VS Code/Cursor configs
- [ ] Update scripts and automation
- [ ] Test MCP connections
- [ ] **Verification**
- [ ] All workspaces registered
- [ ] Task counts match
- [ ] Web UI loads correctly
- [ ] Templates available
- [ ] AI assistant integration works
- [ ] **Cleanup**
- [ ] Remove v0.15 binary (after 30 days)
- [ ] Archive old database
- [ ] Update team documentation
- [ ] Remove old NPM packages
- [ ] **Post-Migration**
- [ ] Explore Web UI
- [ ] Test template aliases
- [ ] Try multi-workspace switching
- [ ] Monitor for issues
---
## Support Resources
### Documentation
- [Quick Start Guide](../guides/getting-started/quick-start.md)
- [Web UI Guide](../guides/features/web-ui.md)
- [Multi-Workspace Guide](../guides/features/multi-workspace.md)
- [Template System Guide](../guides/features/template-system.md)
- [Troubleshooting Guide](../guides/getting-started/troubleshooting.md)
### Community
- **GitHub Issues**: https://github.com/msenol/gorev/issues
- **Discussions**: https://github.com/msenol/gorev/discussions
- **Migration Help**: Tag issues with `migration`
### Getting Help
If you encounter issues:
1. Check [Troubleshooting Guide](../guides/getting-started/troubleshooting.md)
2. Search [existing issues](https://github.com/msenol/gorev/issues)
3. Open new issue with:
- v0.15 version you're migrating from
- Steps you've completed
- Error messages
- Export file size and task count
---
## FAQ
**Q: Can I use v0.15 and v0.16 simultaneously?**
A: Yes, during migration. Install v0.16 via NPM (`gorev-mcp`) while keeping v0.15 binary (`gorev`). They use different databases.
**Q: Will I lose my tasks?**
A: No, if you follow the backup steps. Export before migration, then import to new workspaces.
**Q: Do I need to recreate all tasks manually?**
A: No, use the export/import feature to migrate data automatically.
**Q: Can I go back to v0.15 after migrating?**
A: Yes, follow the rollback plan. Keep backups for 30 days.
**Q: How long does migration take?**
A: 15-30 minutes for most users. Longer if you have 100+ tasks or many projects.
**Q: Will my AI assistant stop working during migration?**
A: Claude/Cursor will temporarily lose connection. Update configs and restart.
**Q: Are there breaking API changes?**
A: Yes, several. See "Breaking Changes" section for details.
**Q: Should I migrate all projects at once?**
A: No, you can migrate gradually. Start with one project, verify, then migrate others.
---
**Migration complete?** 🎉
Explore the new [Web UI](../guides/features/web-ui.md) and [multi-workspace](../guides/features/multi-workspace.md) features!
**Questions?** Open an issue: https://github.com/msenol/gorev/issues
