wehub-resource-sync
249 lines
7.9 KiB
Markdown
249 lines
7.9 KiB
Markdown
---
|
|
allowed-tools: Read, Write, Edit, Bash
|
|
argument-hint: [migration-type] | framework | database | cloud | architecture | --version-upgrade
|
|
description: Create comprehensive migration guides with step-by-step procedures, validation, and rollback strategies
|
|
---
|
|
|
|
# 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:**
|
|
```markdown
|
|
## 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:**
|
|
```markdown
|
|
### Removed: `oldMethod()`
|
|
**Before:**
|
|
```javascript
|
|
const result = library.oldMethod(param1, param2);
|
|
```
|
|
|
|
**After:**
|
|
```javascript
|
|
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**
|
|
|
|
```markdown
|
|
## 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**
|
|
|
|
```markdown
|
|
## 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 |