From 2174312383e3be1d392a7e337e3b71b626af588d Mon Sep 17 00:00:00 2001
From: Ewout ter Hoeven <E.M.terHoeven@student.tudelft.nl>
Date: Fri, 30 Aug 2024 11:22:00 +0200
Subject: [PATCH 1/3] Write initial Mesa Migration guide

Contains a rough outline for a Mesa Migration guide, including Mesa 3.0.

Already wrote something on Reserved and private variables, Removal of mesa.flat namespace, Automatic increase of the `steps` counter
---
 docs/migration_guide.md | 67 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/migration_guide.md

diff --git a/docs/migration_guide.md b/docs/migration_guide.md
new file mode 100644
index 00000000000..65896391241
--- /dev/null
+++ b/docs/migration_guide.md
@@ -0,0 +1,67 @@
+# Mesa Migration guide
+This guide contains breaking changes between major Mesa versions and how to resolve them.
+
+Non-breaking changes aren't included, for those see our [Release history](https://github.com/projectmesa/mesa/releases).
+
+## Mesa 3.0
+<!-- TODO small introduction-->
+
+The development of this deprecation guide is tracked in [Issue #2233](https://github.com/projectmesa/mesa/issues/2233).
+
+### Reserved and private variables
+<!-- TODO: Update this section based on https://github.com/projectmesa/mesa/discussions/2230 -->
+
+#### Reserved variables
+Currently, we have reserved the following variables:
+  - Model: `agents`, `current_id`, `random`, `running`, `steps`, `time`.
+  - Agent: `unique_id`, `model`.
+
+You can use (read) any reserved variable, but Mesa may update them automatically and rely on them, so modify/update at your own risk.
+#### Private variables
+Any variables starting with an underscore (`_`) are considered private and for Mesa's internal use. We might use any of those. Modifying or overwriting any private variable is at your own risk.
+
+- Ref: [Discussion #2230](https://github.com/projectmesa/mesa/discussions/2230), [PR #2225](https://github.com/projectmesa/mesa/pull/2225)
+
+
+### Removal of `mesa.flat` namespace
+The `mesa.flat` namespace is removed. Use the full namespace for your imports.
+
+- Ref: [PR #2091](https://github.com/projectmesa/mesa/pull/2091)
+
+
+### Automatic assignment of `unique_id` to Agents
+<!-- TODO -->
+
+- Ref: [PR #2226](https://github.com/projectmesa/mesa/pull/2226)
+
+
+### AgentSet and `Model.agents`
+#### AgentSet
+<!-- TODO  -->
+
+#### `Model.agents`
+<!-- TODO  -->
+
+
+### Time and schedulers
+<!-- TODO general explanation-->
+
+#### Automatic increase of the `steps` counter
+The `steps` counter is now automatically increased. With each call to `Model.steps()` it's increased by 1, at the beginning of the step.
+
+You can access it by `Model.steps`, and it's internally in the datacollector, batchrunner and the visualisation.
+
+- Ref: [PR #2223](https://github.com/projectmesa/mesa/pull/2223), Mesa-examples [PR #161](https://github.com/projectmesa/mesa-examples/pull/161)
+
+#### Removal of `Model._time` and rename `._steps`
+- `Model._time` is removed. You can define your own time variable if needed.
+- `Model._steps` steps is renamed to `Model.steps`.
+
+#### Removal of `Model._advance_time()`
+- The `Model._advance_time()` method is removed. This now happens automatically.
+
+<!-- TODO deprecate all schedulers? -->
+
+
+### Visualisation
+<!-- TODO -->

From 3edebbaf87cdf3d23809f20119adec1910d8de2e Mon Sep 17 00:00:00 2001
From: Ewout ter Hoeven <E.M.terHoeven@student.tudelft.nl>
Date: Fri, 30 Aug 2024 11:22:29 +0200
Subject: [PATCH 2/3] Add Migration guide to docs index

---
 docs/index.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/index.md b/docs/index.md
index 669f9294a3a..a817d1f9e5e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -81,6 +81,7 @@ ABM features users have shared that you may want to use in your model
 Mesa Overview <overview>
 tutorials/intro_tutorial
 tutorials/visualization_tutorial
+Migration guide <migration_guide>
 Best Practices <best-practices>
 How-to Guide <howto>
 API Documentation <apis/api_main>

From 5787b2ab64d9e86411d7dea0517ec1e8100e1c6b Mon Sep 17 00:00:00 2001
From: Ewout ter Hoeven <E.M.terHoeven@student.tudelft.nl>
Date: Fri, 30 Aug 2024 17:54:27 +0200
Subject: [PATCH 3/3] Update migration_guide.md

---
 docs/migration_guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/migration_guide.md b/docs/migration_guide.md
index 65896391241..9097ea2e34c 100644
--- a/docs/migration_guide.md
+++ b/docs/migration_guide.md
@@ -6,7 +6,7 @@ Non-breaking changes aren't included, for those see our [Release history](https:
 ## Mesa 3.0
 <!-- TODO small introduction-->
 
-The development of this deprecation guide is tracked in [Issue #2233](https://github.com/projectmesa/mesa/issues/2233).
+_This guide is a work in progress. The development of it is tracked in [Issue #2233](https://github.com/projectmesa/mesa/issues/2233)._
 
 ### Reserved and private variables
 <!-- TODO: Update this section based on https://github.com/projectmesa/mesa/discussions/2230 -->