diff --git a/docs/migration/0.11_to_0.12.md b/docs/migration/0.11_to_0.12.md
new file mode 100644
index 00000000..646662c8
--- /dev/null
+++ b/docs/migration/0.11_to_0.12.md
@@ -0,0 +1,32 @@
+(migrate-to-bidsapp)=
+# 0.11 to 0.12+
+
+Snakebids 0.12 introduces a [new, more flexible module](#snakebids.bidsapp) for creating bidsapps. This affects the syntax of the `run.py` file. Older versions used the {class}`snakebids.app.SnakeBidsApp` class to initialize the bidsapp, and this method will still work for the forseeable future. Switching to the new syntax will give access to new plugins and integrations and ensure long term support.
+
+If you haven't heavily modified your `run.py` file, you can transition simply by replacing it with the following:
+
+```python
+#!/usr/bin/env python3
+from pathlib import Path
+
+from snakebids import bidsapp, plugins
+
+app = bidsapp.app(
+    [
+        plugins.SnakemakeBidsApp(Path(__file__).resolve().parent),
+        plugins.BidsValidator(),
+        plugins.Version(distribution="<app_name_here>"),
+    ]
+)
+
+
+def get_parser():
+    """Exposes parser for sphinx doc generation, cwd is the docs dir."""
+    return app.build_parser().parser
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+The snakemake workflow will work in exactly the same way.
diff --git a/docs/migration/0.5_to_0.8.md b/docs/migration/0.5_to_0.8.md
index b33acaff..0cecacd1 100644
--- a/docs/migration/0.5_to_0.8.md
+++ b/docs/migration/0.5_to_0.8.md
@@ -1,4 +1,8 @@
-# 0.5 to 0.8
+# 0.5 to 0.8+
+
+```{note}
+Be sure to also [migrate](0.11_to_0.12.md) your `run.py` file to the new snakebids 0.12 syntax!
+```
 
 Starting in version 0.8, {func}`snakebids.generate_inputs()` returns a {class}`BidsInputs <snakebids.BidsDataset>` object instead of a {class}`dict <snakebids.BidsDatasetDict>`. This requires a change in the way info is accessed. The previous  {class}`dict <snakebids.BidsDatasetDict>` had top-level keys such as `"input_lists"`. After selecting such a key, you would pass the name of a component to get the information sought:
 
diff --git a/docs/migration/0.7_to_0.8.md b/docs/migration/0.7_to_0.8.md
index d4bd61a4..71210b7d 100644
--- a/docs/migration/0.7_to_0.8.md
+++ b/docs/migration/0.7_to_0.8.md
@@ -1,4 +1,4 @@
-# 0.7 to 0.8
+# 0.7 to 0.8+
 
 ````{warning}
 If your code still has bits like this:
@@ -12,6 +12,9 @@ config.update(generate_inputs(
 Check out the [pre-0.6 migration guide](/migration/0.5_to_0.8) to a guide on how to upgrade!
 ````
 
+```{note}
+Be sure to also [migrate](0.11_to_0.12.md) your `run.py` file to the new snakebids 0.12 syntax!
+```
 
 
 ## Default return of {func}`~snakebids.generate_inputs()`
diff --git a/docs/migration/index.md b/docs/migration/index.md
index 2093fe25..539c9d1d 100644
--- a/docs/migration/index.md
+++ b/docs/migration/index.md
@@ -7,4 +7,5 @@ Snakebids has rapidly evolved over the last few versions, resulting in a number
 
 0.5_to_0.8
 0.7_to_0.8
+0.11_to_0.12
 ```