Migration Guide: v0.7.x to v0.8.0¶

Complete guide for migrating from the old directory structure to the new src-layout.

Release Date: 2025-11-06 Breaking Changes: Yes Migration Effort: Low (15-30 minutes)

📋 Summary of Changes¶

Version 0.8.0 introduces a complete restructuring to adopt Python's standard src-layout. This brings better organization, clearer package boundaries, and follows Python best practices.

Major Changes¶

All code moved to src/codebase_rag/
All old entry scripts removed
Import paths updated
New standardized entry points
Backward compatibility removed

🚨 Breaking Changes¶

1. Entry Scripts Removed¶

Old (❌ No longer works):

python start.py
python start_mcp.py
python main.py

New (✅ Use these instead):

# Direct module invocation
python -m codebase_rag          # Start both services
python -m codebase_rag --web    # Web only
python -m codebase_rag --mcp    # MCP only
python -m codebase_rag --version

# After installation (pip install -e .)
codebase-rag          # Main CLI
codebase-rag-web      # Web server
codebase-rag-mcp      # MCP server

2. Import Paths Changed¶

Old (❌ No longer works):

from config import settings
from services.neo4j_knowledge_service import Neo4jKnowledgeService
from services.memory_store import MemoryStore
from core.app import create_app
from api.routes import router
from mcp_tools.utils import some_function

New (✅ Use these instead):

from src.codebase_rag.config import settings
from src.codebase_rag.services.knowledge import Neo4jKnowledgeService
from src.codebase_rag.services.memory import MemoryStore
from src.codebase_rag.core.app import create_app
from src.codebase_rag.api.routes import router
from src.codebase_rag.mcp.utils import some_function

3. Directory Structure Changed¶

Old Structure (❌ Removed):

codebase-rag/
├── api/              # ❌ Deleted
├── core/             # ❌ Deleted
├── services/         # ❌ Deleted
├── mcp_tools/        # ❌ Deleted
├── config.py         # ❌ Deleted
├── main.py           # ❌ Deleted
├── start.py          # ❌ Deleted
└── start_mcp.py      # ❌ Deleted

New Structure (✅ Current):

codebase-rag/
├── src/
│   └── codebase_rag/  # ✅ All code here
│       ├── __init__.py
│       ├── __main__.py
│       ├── config/
│       ├── server/
│       ├── core/
│       ├── api/
│       ├── services/
│       └── mcp/       # Renamed from mcp_tools
├── pyproject.toml     # ✅ Updated
├── docs/
├── tests/
└── ...

4. Docker Changes¶

Dockerfile CMD changed:

# Old
CMD ["python", "start.py"]

# New
CMD ["python", "-m", "codebase_rag"]

🔄 Migration Steps¶

For End Users (Docker Deployment)¶

If you're using Docker, no changes needed! Just pull the new image:

# Pull latest
docker pull royisme/codebase-rag:latest

# Or rebuild
docker-compose down
docker-compose pull
docker-compose up -d

For Developers (Local Development)¶

Step 1: Update Repository¶

# Pull latest changes
git pull origin main

# Or if on a branch
git fetch origin
git rebase origin/main

Step 2: Reinstall Package¶

# Remove old installation
pip uninstall code-graph -y

# Reinstall with new structure
pip install -e .

# Or with uv
uv pip install -e .

Step 3: Update Your Code¶

Update all import statements in your custom scripts/tools:

# Old imports (need to update)
from config import settings
from services.xxx import Yyy

# New imports
from src.codebase_rag.config import settings
from src.codebase_rag.services.xxx import Yyy

Find all files to update:

# Search for old imports in your codebase
grep -r "from config import" .
grep -r "from services\." .
grep -r "from core\." .
grep -r "from api\." .
grep -r "from mcp_tools\." .

Step 4: Update Entry Scripts¶

If you have custom scripts that call the server:

# Old
if __name__ == "__main__":
    from start import main
    main()

# New
if __name__ == "__main__":
    from src.codebase_rag.server.web import main
    main()

Or better, use the standard module invocation:

import subprocess
subprocess.run(["python", "-m", "codebase_rag"])

Step 5: Update MCP Configurations¶

If using MCP (Claude Desktop, Cursor, etc.):

Old claude_desktop_config.json:

{
  "mcpServers": {
    "codebase-rag": {
      "command": "python",
      "args": ["/path/to/codebase-rag/start_mcp.py"]
    }
  }
}

New:

{
  "mcpServers": {
    "codebase-rag": {
      "command": "python",
      "args": ["-m", "codebase_rag", "--mcp"],
      "cwd": "/path/to/codebase-rag"
    }
  }
}

Or after installation:

{
  "mcpServers": {
    "codebase-rag": {
      "command": "codebase-rag-mcp"
    }
  }
}

🧪 Testing Your Migration¶

After migration, test all functionality:

1. Test Import Paths¶

# Test configuration import
from src.codebase_rag.config import settings
print(f"✅ Config: {settings.app_name}")

# Test service imports
from src.codebase_rag.services.knowledge import Neo4jKnowledgeService
print("✅ Services import successful")

2. Test Entry Points¶

# Test version
python -m codebase_rag --version
# Should output: codebase-rag version 0.8.0

# Test help
python -m codebase_rag --help

# Test web server (Ctrl+C to stop)
python -m codebase_rag --web

3. Test Docker¶

# Build test image
docker build -t codebase-rag:test .

# Run test container
docker run -p 8000:8000 -p 8080:8080 codebase-rag:test

# Check health
curl http://localhost:8080/api/v1/health

4. Run Tests¶

# Run test suite
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/codebase_rag --cov-report=html

📝 Common Issues¶

Issue 1: ModuleNotFoundError¶

Error:

ModuleNotFoundError: No module named 'config'

Solution: Update import to new path:

from src.codebase_rag.config import settings

Issue 2: start.py not found¶

Error:

python: can't open file 'start.py': [Errno 2] No such file or directory

Solution: Use new entry point:

python -m codebase_rag

Issue 3: Old imports in tests¶

Error:

ImportError: cannot import name 'Neo4jKnowledgeService' from 'services.neo4j_knowledge_service'

Solution: Update test imports:

from src.codebase_rag.services.knowledge import Neo4jKnowledgeService

Issue 4: Docker container fails to start¶

Error:

python: can't open file 'start.py'

Solution: Rebuild Docker image:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

🎯 Benefits of New Structure¶

1. Standard Python Package¶

✅ Follows PyPA src-layout recommendations
✅ Proper package namespace (codebase_rag)
✅ Cleaner imports

2. Better Organization¶

✅ All source code in src/
✅ Clear separation of concerns
✅ Logical service grouping

3. Easier Development¶

✅ Standard entry points (python -m codebase_rag)
✅ Proper console scripts after installation
✅ No confusion about root vs package code

4. Improved Maintainability¶

✅ No duplicate code
✅ Clear module boundaries
✅ Easier to navigate for new contributors

📚 Additional Resources¶

🆘 Need Help?¶

If you encounter issues not covered in this guide:

Check Troubleshooting
Check FAQ
Open an issue on GitHub
Ask in Discussions

Last Updated: 2025-11-06 Next Version: 0.9.0 (planned)