Migration Guide: v0.1.0 → v0.2.0
Release Date: 2025-10-26 Migration Effort: Low (No breaking changes) Recommended: Yes (Significant stability improvements)
Overview
Yanshi v0.2.0 introduces major stability and observability improvements through Phase 1 enhancements. This release focuses on production-readiness with retry mechanisms, error context tracking, workflow debugging tools, and resource management capabilities.
Key Highlights:
- ✅ Zero Breaking Changes - Fully backward compatible
- ✅ Opt-In Features - All new features are optional
- ✅ Production Ready - Battle-tested with comprehensive test coverage
- ✅ Performance Optimized - Minimal overhead (< 1ms for most operations)
What’s New
1. Retry Mechanism (Week 1)
Automatic retry with configurable strategies for transient failures.
2. Error Context Enhancement (Week 1)
Detailed error tracking with execution history and input capture.
3. Workflow Debugging Tools (Week 2)
CLI command for workflow validation, visualization, and dry-run.
4. Resource Management (Week 3)
Configurable memory limits with automatic cleanup and monitoring.
Migration Steps
Step 1: Update Dependencies
Update your Cargo.toml:
[dependencies]
yanshi-core = "0.2.0"
yanshi-llm = "0.2.0"
yanshi-cli = "0.2.0"
Then run:
cargo update
cargo build
Step 2: Run Tests
Verify your existing workflows still work:
cargo test
Expected Result: All tests should pass without modifications.
Step 3: Adopt New Features (Optional)
3.1 Enable Retry Mechanism
Add retry configuration to error-prone operations:
#![allow(unused)]
fn main() {
use yanshi_core::{RetryPolicy, RetryStrategy, execute_with_retry};
let policy = RetryPolicy::builder()
.max_attempts(3)
.strategy(RetryStrategy::ExponentialBackoff {
initial_delay_ms: 100,
max_delay_ms: 5000,
multiplier: 2.0,
jitter: true,
})
.build();
// Wrap operations that may fail transiently
let result = execute_with_retry(&policy, "api_call", || async {
// Your operation here
Ok(data)
}).await?;
}
3.2 Add Error Context Tracking
Enhance error reporting with detailed context:
#![allow(unused)]
fn main() {
use yanshi_core::{execute_with_retry_and_context, ErrorContext};
let result = execute_with_retry_and_context(
&policy,
"run_123",
"process_node",
Some("data_processor"),
|| async {
// Your operation
Ok(result)
}
).await;
match result {
Ok(value) => // Handle success,
Err((error, context)) => {
// Access detailed error information
eprintln!("{}", context.detailed_report());
}
}
}
3.3 Use Workflow Debugging
Debug workflows before execution:
# Validate workflow configuration
yanshi workflow debug workflow.yml --validate
# Visualize DAG structure
yanshi workflow debug workflow.yml --visualize
# Analyze complexity and bottlenecks
yanshi workflow debug workflow.yml --analyze
# Dry-run without execution
yanshi workflow debug workflow.yml --dry-run
3.4 Enable Resource Management
Add memory limits to prevent unbounded growth:
#![allow(unused)]
fn main() {
use yanshi_core::{ResourceLimits, StateMonitor};
let limits = ResourceLimits::builder()
.max_state_size(100 * 1024 * 1024) // 100 MB
.max_value_size(10 * 1024 * 1024) // 10 MB
.cleanup_threshold(0.8) // Clean at 80%
.auto_cleanup(true)
.build();
let monitor = StateMonitor::new(limits);
// Track allocations
monitor.record_allocation("data", data.len());
// Check usage
let stats = monitor.get_stats();
if stats.should_cleanup {
monitor.cleanup(0.5)?; // Clean to 50%
}
// Cleanup when done
monitor.record_deallocation("data");
}
API Changes
No Breaking Changes ✅
All existing APIs remain unchanged and fully functional.
New APIs Added
Retry Module
RetryPolicy- Retry configurationRetryStrategy- Retry timing strategiesRetryContext- Retry attempt trackingexecute_with_retry()- Simple retry wrapperexecute_with_retry_and_context()- Retry with error context
Error Context Module
ErrorContext- Detailed error informationErrorInfo- Individual error detailsErrorContextBuilder- Fluent API for context creation
Resource Management Module
ResourceLimits- Memory limit configurationStateMonitor- Real-time usage trackingResourceAlert- Usage notificationsResourceStats- Usage statistics
CLI Commands
yanshi workflow debug- Workflow debugging command--validate- Validate configuration--visualize- Show DAG structure--analyze- Analyze complexity--plan- Show execution plan--dry-run- Simulate execution
Performance Impact
Overhead Measurements
All features have minimal performance impact:
| Feature | Overhead | Acceptable? |
|---|---|---|
| Retry (no retries) | < 100μs | ✅ Yes |
| Retry (with retries) | < 5ms per retry | ✅ Yes |
| Error context | < 1ms | ✅ Yes |
| Resource tracking | < 10μs per operation | ✅ Yes |
| Resource cleanup | < 10ms for 50 entries | ✅ Yes |
Optimization Tips
-
Use Fast Mode for Resource Monitoring (when LRU not needed):
#![allow(unused)] fn main() { let monitor = StateMonitor::new_fast(limits); // 80x faster } -
Disable Features You Don’t Use:
#![allow(unused)] fn main() { // If not using error context, use simple retry execute_with_retry(&policy, "op", || async { Ok(()) }).await } -
Configure Appropriate Limits:
#![allow(unused)] fn main() { // Don't use unlimited values let limits = ResourceLimits::builder() .max_state_size(available_memory / 2) // Use 50% of available .build(); }
Common Migration Scenarios
Scenario 1: Basic Usage (No Changes Needed)
Before v0.2.0:
#![allow(unused)]
fn main() {
let flow = Flow::new(nodes);
let results = flow.run().await?;
}
After v0.2.0:
#![allow(unused)]
fn main() {
// Exact same code works!
let flow = Flow::new(nodes);
let results = flow.run().await?;
}
Migration Effort: None ✅
Scenario 2: Adding Retry to Existing Code
Before v0.2.0:
#![allow(unused)]
fn main() {
async fn fetch_data() -> Result<Data, Error> {
// Manual retry logic
for attempt in 0..3 {
match api_call().await {
Ok(data) => return Ok(data),
Err(e) if attempt < 2 => {
tokio::time::sleep(Duration::from_millis(100)).await;
continue;
}
Err(e) => return Err(e),
}
}
unreachable!()
}
}
After v0.2.0:
#![allow(unused)]
fn main() {
async fn fetch_data() -> Result<Data, YanshiError> {
let policy = RetryPolicy::builder()
.max_attempts(3)
.strategy(RetryStrategy::Fixed { delay_ms: 100 })
.build();
execute_with_retry(&policy, "fetch_data", || async {
api_call().await.map_err(|e| YanshiError::Generic(e.to_string()))
}).await
}
}
Benefits: Less code, more reliable, configurable
Scenario 3: Improving Error Handling
Before v0.2.0:
#![allow(unused)]
fn main() {
match workflow.execute().await {
Ok(result) => println!("Success: {:?}", result),
Err(e) => eprintln!("Error: {}", e), // Limited information
}
}
After v0.2.0:
#![allow(unused)]
fn main() {
match execute_with_retry_and_context(
&policy,
run_id,
node_name,
Some(node_type),
|| async { workflow.execute().await }
).await {
Ok(result) => println!("Success: {:?}", result),
Err((error, context)) => {
eprintln!("{}", context.detailed_report()); // Rich debugging info
// Log context for debugging
log::error!("Workflow failed: {}", context.summary());
}
}
}
Benefits: Better debugging, root cause analysis, audit trail
Scenario 4: Adding Resource Monitoring
Before v0.2.0:
#![allow(unused)]
fn main() {
// No memory tracking - potential OOM
let mut state = HashMap::new();
for item in large_dataset {
state.insert(item.id, item.data); // Unbounded growth!
}
}
After v0.2.0:
#![allow(unused)]
fn main() {
let limits = ResourceLimits::builder()
.max_state_size(100 * 1024 * 1024)
.auto_cleanup(true)
.build();
let monitor = StateMonitor::new(limits);
let mut state = HashMap::new();
for item in large_dataset {
let size = std::mem::size_of_val(&item.data);
if !monitor.record_allocation(&item.id, size) {
// Handle resource limit
monitor.cleanup(0.5)?;
if !monitor.record_allocation(&item.id, size) {
return Err(YanshiError::ResourcePoolExhausted {
resource_type: "memory".to_string()
});
}
}
state.insert(item.id, item.data);
}
}
Benefits: Predictable memory usage, automatic cleanup, no OOM
Troubleshooting
Issue: Tests Fail After Update
Cause: Compilation errors or test failures after upgrading.
Solution:
- Clean build artifacts:
cargo clean - Update all dependencies:
cargo update - Rebuild:
cargo build - If using unstable features, check compatibility
Issue: Performance Regression
Cause: Unintended feature overhead.
Solution:
- Use fast mode for resource monitoring if not using cleanup
- Disable retry for non-transient operations
- Check benchmark results:
cargo test --test performance_benchmarks
Issue: Memory Usage Increased
Cause: Error context or resource monitoring tracking data.
Solution:
- Use
StateMonitor::new_fast()for minimal overhead - Configure appropriate
max_cache_entries - Enable auto cleanup:
.auto_cleanup(true)
Rollback Instructions
If you need to revert to v0.1.0:
[dependencies]
yanshi-core = "0.1.0"
yanshi-llm = "0.1.0"
yanshi-cli = "0.1.0"
Then:
cargo clean
cargo update
cargo build
Note: No code changes needed since v0.2.0 is backward compatible.
Testing Checklist
Before deploying v0.2.0 to production:
- All existing tests pass without modification
- Integration tests run successfully
- Performance benchmarks meet targets
- Resource limits configured appropriately
- Error handling tested with new context
- Retry policies tested for your use cases
- Workflow debugging commands work
- Memory usage monitored and acceptable
Getting Help
- Documentation:
docs/directory - Examples:
yanshi-core/examples/ - Issues: https://github.com/anthropics/yanshi/issues
- Discussions: https://github.com/anthropics/yanshi/discussions
Related Documentation
- RETRY_MECHANISM.md - Retry configuration guide
- WORKFLOW_DEBUGGING.md - Debugging tools guide
- RESOURCE_MANAGEMENT.md - Resource management guide
- RELEASE_NOTES_v0.2.0.md - Complete changelog
Last Updated: 2025-10-26 Version: 0.2.0 Status: Ready for Review