From 42e8a6522701fabe874ec8e028ca9ce8017f5cb4 Mon Sep 17 00:00:00 2001
From: Marek Wolan <marek.wolan@methods.co.uk>
Date: Tue, 11 Jul 2023 12:01:48 +0100
Subject: [PATCH] Added draft migration guide.

---
 docs/index.rst                      |  1 +
 docs/source/migration_1.2_-_2.0.rst | 43 +++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/source/migration_1.2_-_2.0.rst

diff --git a/docs/index.rst b/docs/index.rst
index 02baa695..fed65919 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -39,6 +39,7 @@ The best place to start is :ref:`about`
    PrimAITE Tests <source/_autosummary/tests>
    source/dependencies
    source/glossary
+   source/migration_1.2_-_2.0
 
 .. toctree::
    :caption: Project Links:
diff --git a/docs/source/migration_1.2_-_2.0.rst b/docs/source/migration_1.2_-_2.0.rst
new file mode 100644
index 00000000..99cb891b
--- /dev/null
+++ b/docs/source/migration_1.2_-_2.0.rst
@@ -0,0 +1,43 @@
+v1.2 to v2.0 Migration guide
+============================
+
+**1. Running a training session**
+
+    In version 1.2 of PrimAITE, the main entry point for training or evaluating agents was the ``src/primaite/main.py`` file. v2.0.0 introduced managed 'sessions' which are responsible for reading configuration files, performing training, and writing outputs.
+
+    ``main.py`` file still runs a training session but it now uses the new `PrimaiteSession`, and it now requires you to provide the path to your config files.
+
+    .. code-block:: bash
+
+        python src/primaite/main.py --tc path/to/training-config.yaml --ldc path/to/laydown-config.yaml
+
+    Alternatively, the session can be invoked via the commandline by running:
+
+    .. code-block:: bash
+
+        primaite session --tc path/to/training-config.yaml --ldc path/to/laydown-config.yaml
+
+**2. Location of configs**
+
+    In version 1.2, training configs and laydown configs were all stored in the project repository under ``src/primaite/config``. Version 2.0.0 introduced user data directories, and now when you install and setup PrimAITE, config files are stored in your user data location. On Linux/OSX, this is stored in ``~/primaite/config``. On Windows, this is stored in ``C:\Users\<your username>\primaite\configs``. Upon first setup, the configs folder is populated with some default yaml files. It is recommended that you store all your custom configuration files here.
+
+**3. Contents of configs**
+
+    Some things that were previously part of the laydown config are now part of the traning config.
+
+        * Actions
+
+    If you have custom configs which use these, you will need to adapt them by moving the configuration from the laydown config to the training config.
+
+    Also, there are new configurable items in the training config:
+
+        * Observations
+        * Agent framework
+        * Agent
+        * Deep learning framework
+        * random red agents
+        * seed
+        * deterministic
+        * hard coded agent view
+
+    Each of these items have default values which are designed so that PrimAITE has the same behaviour as it did in 1.2.0, so you do not have to specify them.