gabrielmoreira Migration Guide
Core Workflow
- Identify source version, target version, audience, breaking changes, and migration deadline.
- Separate required changes from optional improvements.
- Provide step-by-step migration instructions with verification after each risky step.
- Include compatibility notes, rollback path, known issues, and support path.
- Preserve platform/vendor alternatives when the project is vendor-neutral.
- Flag unknowns, unsupported paths, and user-specific decisions.
Safety Rules
- Do not invent compatibility, deprecation, or rollback guarantees.
- Do not hide data loss, downtime, security, or breaking-change risks.
- Do not provide destructive migration commands without review and backups.
Deliverable Shape
For migration guides, provide:
- Who must migrate
- Source and target versions
- What changed
- Required steps
- Verification checks
- Rollback or fallback path
- Known issues
- Support or escalation path
References
- Read
references/migration-guide-checklist.mdwhen writing or reviewing migration guidance.