Split documentation by target

2 files changed, 49 insertions, 0 deletions

diff --git a/docs/source/devel/index.rst b/docs/source/devel/index.rst
new file mode 100644
index 0000000..cdaa532
--- /dev/null
+++ b/docs/source/devel/index.rst
@@ -0,0 +1,13 @@
+#########################
+ Developer Documentation
+#########################
+
+Documentation that is useful for developers who are using lesana as a
+library.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   promises
+
diff --git a/docs/source/devel/promises.rst b/docs/source/devel/promises.rst
new file mode 100644
index 0000000..6a3b04e
--- /dev/null
+++ b/docs/source/devel/promises.rst
@@ -0,0 +1,36 @@
+********
+Promises
+********
+
+Semantic versioning
+===================
+
+This project uses semver_.
+
+.. _semver: http://semver.org/
+
+Collection format stability
+===========================
+
+Future versions of lesana will be able to read collections written by
+older versions.
+
+Older versions in the same mayor release will also be able to work
+concurrently on the same repository.
+
+If in the future a change of formats will be required, conversions
+scripts will be written in a way that will make them as stable as
+possibile, and will have enought test data to keep them maintained for
+the time being.
+
+Disposable cache
+================
+
+Contrary to the yaml files, the xapian cache is considered disposable:
+from time to time there may be a need to delete the cache and reindex
+everything, either because of an upgrade or to perform repository
+mainteinance.
+
+Of course, effort will be made to reduce the need for this so that it
+only happens sporadically, but it will probably never completely
+disappear.