From 65a0da97c3170fcea54eb8fd78885f802b3a8bc2 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Fri, 31 Oct 2014 11:08:45 -0400 Subject: [PATCH] add interface stability docs --- doc/contributing.mdwn | 6 +++++- doc/interface_stability.mdwn | 13 +++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 doc/interface_stability.mdwn diff --git a/doc/contributing.mdwn b/doc/contributing.mdwn index 33b34a6..84aa5d6 100644 --- a/doc/contributing.mdwn +++ b/doc/contributing.mdwn @@ -3,7 +3,11 @@ modify and distribute it; indeed doing so is a fundamental part of how propellor is configured and used. You don't have to contribute your patches, but you're encouraged to do so; -let's all make propellor awesome together! Patches can be sent to +let's all make propellor awesome together! Also, contributing patches is a +good way to make sure that your code keeps working in new versions of +propellor. See [[interface_stability]]. + +Patches can be sent to or pull requests can be posted to [[todo]]. To certify that a change is released under propellor's BSD license, diff --git a/doc/interface_stability.mdwn b/doc/interface_stability.mdwn new file mode 100644 index 0000000..8ad5dfd --- /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.