Migration Guide Generator

Create comprehensive migration guide: $ARGUMENTS

Current System Analysis

• Current versions: @package.json or @requirements.txt or detect from lock files
• Migration history: !find . -name "*migration*" -o -name "*upgrade*" | head -5
• Database schema: !find . -name "*schema*" -o -name "*.sql" | head -3
• Dependencies: !grep -c "dependency\|require\|import" package.json requirements.txt 2>/dev/null || echo "0"
• Infrastructure: @docker-compose.yml or @k8s/ or @terraform/ (if exists)

Task

Generate systematic migration guide with comprehensive safety measures: $ARGUMENTS

1. Migration Scope Analysis

   • Identify what is being migrated (framework, library, architecture, etc.)
   • Determine source and target versions or technologies
   • Assess the scale and complexity of the migration
   • Identify affected systems and components

2. Impact Assessment

   • Analyze breaking changes between versions
   • Identify deprecated features and APIs
   • Review new features and capabilities
   • Assess compatibility requirements and constraints
   • Evaluate performance and security implications

3. Prerequisites and Requirements

   • Document system requirements for the target version
   • List required tools and dependencies
   • Specify minimum versions and compatibility requirements
   • Identify necessary skills and team preparation
   • Outline infrastructure and environment needs

4. Pre-Migration Preparation

   • Create comprehensive backup strategies
   • Set up development and testing environments
   • Document current system state and configurations
   • Establish rollback procedures and contingency plans
   • Create migration timeline and milestones

5. Step-by-Step Migration Process

   Example for Framework Upgrade:

   ## Step 1: Environment Setup
   1. Update development environment
   2. Install new framework version
   3. Update build tools and dependencies
   4. Configure IDE and tooling
   
   ## Step 2: Dependencies Update
   1. Update package.json/requirements.txt
   2. Resolve dependency conflicts
   3. Update related libraries
   4. Test compatibility
   
   ## Step 3: Code Migration
   1. Update import statements
   2. Replace deprecated APIs
   3. Update configuration files
   4. Modify build scripts
   

6. Breaking Changes Documentation

   • List all breaking changes with examples
   • Provide before/after code comparisons
   • Explain the rationale behind changes
   • Offer alternative approaches for removed features

   Example Breaking Change:

   ### Removed: `oldMethod()`
   **Before:**
   ```javascript
   const result = library.oldMethod(param1, param2);
   

   After:

   const result = library.newMethod({ 
     param1: param1, 
     param2: param2 
   });
   

   Rationale: Improved type safety and extensibility

7. Configuration Changes

   • Document configuration file updates
   • Explain new configuration options
   • Provide configuration migration scripts
   • Show environment-specific configurations

8. Database Migration (if applicable)

   • Create database schema migration scripts
   • Document data transformation requirements
   • Provide backup and restore procedures
   • Test migration with sample data
   • Plan for zero-downtime migrations

9. Testing Strategy

   • Update existing tests for new APIs
   • Create migration-specific test cases
   • Implement integration and E2E tests
   • Set up performance and load testing
   • Document test scenarios and expected outcomes

10. Performance Considerations

    • Document performance changes and optimizations
    • Provide benchmarking guidelines
    • Identify potential performance regressions
    • Suggest monitoring and alerting updates
    • Include memory and resource usage changes

11. Security Updates

    • Document security improvements and changes
    • Update authentication and authorization code
    • Review and update security configurations
    • Update dependency security scanning
    • Document new security best practices

12. Deployment Strategy

    • Plan phased rollout approach
    • Create deployment scripts and automation
    • Set up monitoring and health checks
    • Plan for blue-green or canary deployments
    • Document rollback procedures

13. Common Issues and Troubleshooting

    ## Common Migration Issues
    
    ### Issue: Import/Module Resolution Errors
    **Symptoms:** Cannot resolve module 'old-package'
    **Solution:** 
    1. Update import statements to new package names
    2. Check package.json for correct dependencies
    3. Clear node_modules and reinstall
    
    ### Issue: API Method Not Found
    **Symptoms:** TypeError: oldMethod is not a function
    **Solution:** Replace with new API as documented in step 3
    

14. Team Communication and Training

    • Create team training materials
    • Schedule knowledge sharing sessions
    • Document new development workflows
    • Update coding standards and guidelines
    • Create quick reference guides

15. Tools and Automation

    • Provide migration scripts and utilities
    • Create code transformation tools (codemods)
    • Set up automated compatibility checks
    • Implement CI/CD pipeline updates
    • Create validation and verification tools

16. Timeline and Milestones

    ## Migration Timeline
    
    ### Phase 1: Preparation (Week 1-2)
    - [ ] Environment setup
    - [ ] Team training
    - [ ] Development environment migration
    
    ### Phase 2: Development (Week 3-6)
    - [ ] Core application migration
    - [ ] Testing and validation
    - [ ] Performance optimization
    
    ### Phase 3: Deployment (Week 7-8)
    - [ ] Staging deployment
    - [ ] Production deployment
    - [ ] Monitoring and support
    

17. Risk Mitigation

    • Identify potential migration risks
    • Create contingency plans for each risk
    • Document escalation procedures
    • Plan for extended timeline scenarios
    • Prepare communication for stakeholders

18. Post-Migration Tasks

    • Clean up deprecated code and configurations
    • Update documentation and README files
    • Review and optimize new implementation
    • Conduct post-migration retrospective
    • Plan for future maintenance and updates

19. Validation and Testing

    • Create comprehensive test plans
    • Document acceptance criteria
    • Set up automated regression testing
    • Plan user acceptance testing
    • Implement monitoring and alerting

20. Documentation Updates

    • Update API documentation
    • Revise development guides
    • Update deployment documentation
    • Create troubleshooting guides
    • Update team onboarding materials

Migration Types and Specific Considerations:

Framework Migration (React 17 → 18):

• Update React and ReactDOM imports
• Replace deprecated lifecycle methods
• Update testing library methods
• Handle concurrent features and Suspense

Database Migration (MySQL → PostgreSQL):

• Convert SQL syntax differences
• Update data types and constraints
• Migrate stored procedures to functions
• Update ORM configurations

Cloud Migration (On-premise → AWS):

• Containerize applications
• Update CI/CD pipelines
• Configure cloud services
• Implement infrastructure as code

Architecture Migration (Monolith → Microservices):

• Identify service boundaries
• Implement inter-service communication
• Set up service discovery
• Plan data consistency strategies

Remember to:

• Test thoroughly in non-production environments first
• Communicate progress and issues regularly
• Document lessons learned for future migrations
• Keep the migration guide updated based on real experiences