Migration Guide

Đang tải…

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

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

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

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

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

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

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

Configuration Changes

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

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

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

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

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

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

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

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

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

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

Risk Mitigation

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

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

Validation and Testing

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

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

Lệnh cài

Nội dung tệp nguồn

Migration Guide Generator

Current System Analysis

Task

Commands khác trong Tài liệu