add interface stability docs

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/interface_stability.mdwn b/doc/interface_stability.mdwn
new file mode 100644
index 00000000..8ad5dfd8
--- /dev/null
+++ b/doc/interface_stability.mdwn
@@ -0,0 +1,13 @@
+Propellor is versioned using the Haskell [Package Version Policy](https://www.haskell.org/haskellwiki/Package_versioning_policy).
+
+This means that propellor 0.10.x contains some changes to its API;
+code written for propellor 0.9.x may need to be changed. Conversely,
+there are no breaking changes between 0.10.1 and 0.10.2.
+
+Whenever possible, breaking changes are made in a way that either changes a
+data type, or a function name, so that code that used the old API version
+won't compile under the new one.
+
+Sometimes, changes to the behavior of properties also merit a major version
+change. For example, propellor 0.8.0 completely revamped the privdata
+storage, and users had to manually transition.