# Migrating from Autosurgeon to Automorph
Welcome! This guide helps you transition from [autosurgeon](https://github.com/automerge/autosurgeon) to Automorph. Both libraries serve the same wonderful goal: making Automerge accessible to Rust developers. We're grateful for the foundation autosurgeon laid for the ecosystem.
## TL;DR - What to Expect
**The essence:** Autosurgeon uses separate `Reconcile` and `Hydrate` traits; Automorph uses a single `Automorph` trait. Most code changes are mechanical renames and slight API adjustments.
**Time estimate:** Small projects (under 20 structs): 30-60 minutes. Medium projects: a few hours. Large projects: consider migrating module by module.
**Key mindset shift:** While autosurgeon treats document operations like serialization, Automorph embraces document *synchronization* with optional change tracking. Both approaches work beautifully—Automorph simply offers additional tools for observing what changed.
## Quick Comparison
| `Reconcile + Hydrate` | `Automorph` | One trait instead of two |
| `reconcile(&mut self, doc, ...)` | `save(&self, doc, ...)` | Immutable self, different args |
| `hydrate(doc, ...)` | `load(doc, ...)` | Similar concept, static method |
| `Option<Reconcile>` | `Option<T>` implements `Automorph` | Built-in support |
| Manual change detection | `diff()`, `update()`, `Tracked<T>` | Optional enhancement |
## Migration Documents
We've organized the migration into focused documents so you can find exactly what you need:
### [1. Step-by-Step Migration Guide](./step-by-step.md)
A hands-on walkthrough for migrating your first module. Includes before/after code samples and checklists.
### [2. Migration Recipes](./recipes.md)
"How do I...?" answers for common patterns. Quick lookup for specific situations like enums, generics, and custom types.
### [3. Conceptual Differences](./concepts.md)
Understanding the philosophical and architectural differences. Useful when making design decisions in your migrated code.
### [4. Feature Mapping](./feature-mapping.md)
A detailed table of autosurgeon features and their Automorph equivalents (or reasons why something might work differently).
### [5. Frequently Asked Questions](./faq.md)
Common concerns and clarifications about the migration process.
### [6. Troubleshooting](./troubleshooting.md)
What to do when things don't compile or behave unexpectedly after migration.
### [7. Working Examples](./examples.rs)
A complete, runnable Rust file with all migration patterns demonstrated and tested. You can copy-paste from this file with confidence.
**To run the examples:**
```bash
# Run the migration examples test
cargo test --test migration_examples
# Or run as a binary
cargo run --example migration_examples # If set up as an example
```
## Migration Philosophy
Autosurgeon and Automorph share deep respect for Automerge's CRDT semantics. Neither is "better"—they explore different design spaces:
- **Autosurgeon** provides a clean, serialization-inspired interface that many developers find intuitive and familiar.
- **Automorph** explores richer change tracking and synchronization semantics, which can be powerful when you need them.
Your existing autosurgeon code works well and will continue to work. Migrate if Automorph's additional capabilities serve your use case, or if you prefer the unified trait approach. There's no urgency—take your time.
## Getting Help
- **Autosurgeon community:** Continue to use the [autosurgeon discussions](https://github.com/automerge/autosurgeon/discussions) for autosurgeon questions
- **Automorph issues:** File issues at the [Codeberg repository](https://codeberg.org/dpp/automorph)
- **Automerge community:** Both projects participate in the broader [Automerge ecosystem](https://automerge.org/)
## Acknowledgments
Autosurgeon pioneered the derive-macro approach for Automerge in Rust. Its design decisions were carefully considered and served the community well. Automorph builds upon those insights, exploring different trade-offs. We're thankful for the path autosurgeon cleared.
---
Ready? Start with the [Step-by-Step Migration Guide](./step-by-step.md) or jump to [Migration Recipes](./recipes.md) if you prefer a reference approach.