## 1. Documentation Setup
- [ ] 1.1 Create `docs/migration-guide.md` file with initial structure
- [ ] 1.2 Add document header with version target (0.4.0) and last updated date
## 2. Migration Guide Content - Overview Section
- [ ] 2.1 Write overview section explaining API evolution motivation
- [ ] 2.2 Document benefits of new workflow-centric API
- [ ] 2.3 Add conceptual explanation of Job → Workflow transition
## 3. Migration Guide Content - Breaking Changes
- [ ] 3.1 Create breaking changes section with categorized list
- [ ] 3.2 Document `Job` → `Workflow` type rename
- [ ] 3.3 Document `JobBuilder` → `WorkflowBuilder` migration
- [ ] 3.4 Document `MaestroK8sClient` → `MaestroClient` builder pattern change
- [ ] 3.5 Document `create_job()` → `create_workflow()` method rename
- [ ] 3.6 Document `dry_run` parameter move from functions to client builder
- [ ] 3.7 Document `entities::job` → `workflows` module change
- [ ] 3.8 Document new traits system (`WorkFlowStep`, `ResourceLimitedStep`)
- [ ] 3.9 Document new features (`ExecutionMode`, `CheckpointConfig`, dependency chains)
## 4. Migration Guide Content - Code Examples
- [ ] 4.1 Add client creation example (old `MaestroK8sClient::new().await?` vs new builder)
- [ ] 4.2 Add job/workflow creation example (old `JobBuilder` vs new `WorkflowBuilder`)
- [ ] 4.3 Add execution and waiting example (old `job.wait().await?` vs new pattern)
- [ ] 4.4 Add cleanup/deletion example (old `delete_job(dry_run)` vs new pattern)
- [ ] 4.5 Add dry_run configuration example (per-call vs client-level)
- [ ] 4.6 Add container configuration example showing trait-based approach
- [ ] 4.7 Add complete end-to-end migration example
## 5. Migration Guide Content - Module Structure Mapping
- [ ] 5.1 Create module mapping table (`entities::job` → `workflows`)
- [ ] 5.2 Document type location changes
- [ ] 5.3 Document function location changes
## 6. Migration Guide Content - Common Pitfalls
- [ ] 6.1 Document pitfall: Forgetting to call `.build()` on client builder
- [ ] 6.2 Document pitfall: Using old namespace patterns
- [ ] 6.3 Document pitfall: Missing required workflow name
- [ ] 6.4 Document pitfall: Incorrect step implementation for new traits
- [ ] 6.5 Document pitfall: dry_run configuration placement
- [ ] 6.6 Add solutions for each documented pitfall
## 7. Migration Guide Content - FAQ
- [ ] 7.1 Add FAQ: "Do I need to migrate immediately?"
- [ ] 7.2 Add FAQ: "Will my old code continue to work?"
- [ ] 7.3 Add FAQ: "How do I handle multi-step workflows?"
- [ ] 7.4 Add FAQ: "What about existing Kubernetes Job resources?"
- [ ] 7.5 Add FAQ: "How do I test the migration?"
- [ ] 7.6 Add FAQ: "Where can I get help?"
## 8. Migration Utilities Module
- [ ] 8.1 Create `src/migration/mod.rs` module file
- [ ] 8.2 Add module documentation with usage examples
- [ ] 8.3 Add `#[deprecated]` attribute macro helpers
- [ ] 8.4 Create type alias: `JobBuilder` → `WorkflowBuilder` (deprecated)
- [ ] 8.5 Create type alias: `Job` → `Workflow` where applicable (deprecated)
- [ ] 8.6 Add deprecation warnings with version and migration notes
- [ ] 8.7 Ensure all utilities are compile-time only (no runtime overhead)
## 9. Integration and Testing
- [ ] 9.1 Add migration module to `src/lib.rs` exports
- [ ] 9.2 Verify all code examples in migration guide compile
- [ ] 9.3 Test type aliases produce correct deprecation warnings
- [ ] 9.4 Run `cargo clippy` on new code
- [ ] 9.5 Run `cargo fmt --check` on new code
- [ ] 9.6 Run `cargo test` to ensure no regressions
## 10. Documentation Updates
- [ ] 10.1 Update CHANGELOG.md with migration notes for version 0.4.0
- [ ] 10.2 Add migration guide link to README.md
- [ ] 10.3 Update lib.rs documentation with migration guidance
- [ ] 10.4 Add deprecation notices to old example files