From 3cd9261d0330e046bb7370482e8ee8c4986bf47c Mon Sep 17 00:00:00 2001
From: Urs Enzler <urs.enzler@gmail.com>
Date: Wed, 4 Dec 2019 09:41:34 +0100
Subject: [PATCH] added documentation for migration to V 5

---
 README.md                      |  3 +-
 documentation/migratingToV5.md | 67 ++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 documentation/migratingToV5.md

diff --git a/README.md b/README.md
index 9b76811..cbe5147 100644
--- a/README.md
+++ b/README.md
@@ -118,4 +118,5 @@ public class SimpleStateMachine
 ## More Documentation
 
 - [Tutorial](documentation/tutorial.md)
-- [Example](documentation/example.md)
\ No newline at end of file
+- [Example](documentation/example.md)
+- [Migrating to V5.x](documentation/migratingToV5.md)
\ No newline at end of file
diff --git a/documentation/migratingToV5.md b/documentation/migratingToV5.md
new file mode 100644
index 0000000..a02cfb0
--- /dev/null
+++ b/documentation/migratingToV5.md
@@ -0,0 +1,67 @@
+# Migrating to Version 5
+
+In Version 5, we split the state machine usage into three distinct steps:
+- Define the state machine
+- Create a state machine from the definition
+- Run the state machine
+
+State machines can now be quickly created from an existing definition.
+
+An example state machine prior to version 5:
+```c#
+var machine = new PassiveStateMachine<States, Events>("my state machine");
+
+machine
+    .In(States.Off)
+    .On(Events.TurnOn)
+        .Goto(States.On)
+        .Execute(SayHello);
+
+machine
+    .In(States.On)
+    .On(Events.TurnOff)
+        .Goto(States.Off)
+        .Execute(SayBye);
+
+machine
+    .Initialize(States.Off);
+
+machine
+    .Start();
+```
+
+In version 5, the same state machine looks like this:
+```c#
+// create a definition builder
+var builder = new StateMachineDefinitionBuilder<States, Events>();
+
+builder
+    .In(States.Off)
+    .On(Events.TurnOn)
+        .Goto(States.On)
+        .Execute(SayHello);
+
+builder
+    .In(States.On)
+    .On(Events.TurnOff)
+        .Goto(States.Off)
+        .Execute(SayBye);
+
+builder
+    .WithInitialState(States.Off); // the initial state is now set during definition time
+
+// create the definition to later spawn state machines from it
+var definition = builder
+    .Build();
+
+// create as many state machines as you need from the same definition
+var machine =    
+    .CreatePassiveStateMachine("my state machine"); // you can also create an active state machine
+
+machine
+    .Start();
+```
+
+Make sure you use the correct `StateMachineDefinitionBuilder`:
+- from namespace `Appccelerate.StateMachine.Machine` for state machines **without** async/await support
+- from namespace `Appccelerate.StateMachine.AsyncMachine` for state machines **with** async/await support
\ No newline at end of file