docs: Add MIGRATION

tmux-python · Oct 7, 2022 · b33b66d · b33b66d
1 parent 0b24c31
commit b33b66d
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 0 deletions.
diff --git a/MIGRATION b/MIGRATION
@@ -0,0 +1,28 @@
+# Migration notes
+
+Migration and deprecation notes for libtmux are here, see {ref}`changelog` as
+well.
+
+```{admonition} Welcome on board! 👋
+1. 📌 For safety, **always** pin the package
+2. 📖 Check the migration notes _(You are here)_
+3. 📣 If you feel something got deprecated and it interrupted you - past, present, or future - voice your opinion on the [tracker].
+
+   We want to make libtmux fun, reliable, and useful for users.
+
+   API changes can be painful.
+
+   If we can do something to draw the sting, we'll do it. We're taking a balanced approach. That's why these notes are here!
+
+   (Please pin the package. 🙏)
+
+   [tracker]: https://github.com/tmux-python/libtmux/discussions
+```
+
+## Next release
+
+_Add migration notes here_
+
+<!---
+# vim: set filetype=markdown:
+-->
diff --git a/docs/index.md b/docs/index.md
@@ -29,6 +29,7 @@ pytest-plugin/index
 developing
 internals/index
 history
+migration
 glossary
 GitHub <https://github.com/tmux-python/libtmux>
 ```
diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,9 @@
+(migration)=
+
+```{currentmodule} libtmux
+
+```
+
+```{include} ../MIGRATION
+
+```