docs: Add migration notes

vcs-python · Oct 8, 2022 · fe3804f · fe3804f
1 parent afefc60
commit fe3804f
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 vcspull 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 vcspull 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/vcs-python/vcspull/discussions
+```
+
+## Next release
+
+_Add migration notes here_
+
+<!---
+# vim: set filetype=markdown:
+-->
diff --git a/docs/index.md b/docs/index.md
@@ -35,5 +35,6 @@ configuration/index
 api
 developing
 history
+migration
 GitHub <https://github.com/vcs-python/vcspull>
 ```
diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,9 @@
+(migration)=
+
+```{currentmodule} libtmux
+
+```
+
+```{include} ../MIGRATION
+
+```