From 4c5accb5125bfa0d3b8357f066747c81b9df4e19 Mon Sep 17 00:00:00 2001
From: Benjamin Bertrand <benjamin.bertrand@ess.eu>
Date: Thu, 19 Nov 2020 14:51:04 +0100
Subject: [PATCH] Add documentation about database versioning
---
docs/development/design.rst | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git a/docs/development/design.rst b/docs/development/design.rst
index e27ce06..ed8cfaf 100644
--- a/docs/development/design.rst
+++ b/docs/development/design.rst
@@ -162,6 +162,31 @@ has the proper access (based on the network)::
if not current_user.has_access_to_network(interface.network):
abort(403)
+Database versioning
+-------------------
+
+SQLAlchemy-Continuum_ is used to track changes and keep an history.
+
+To enable versioning on a models, the ``__versioned__`` attribute shall be added to the model class.
+The following classes are versioned:
+
+- :class:`~app.models.Item`
+- :class:`~app.models.Host`
+- :class:`~app.models.AnsibleGroup`
+
+The *History* on the view host or view group page displays the list of changes performed.
+As there is a relationship between Host and AnsibleGroup, it can lead to unexpected behavior.
+
+1. Edit a group to add a host -> new host added to the group history
+2. Edit another host to add it to that group -> new group added to the host history
+
+At this point the group page will show 2 hosts but only one was added in the history.
+If the group is edited, to add a variable, the recorded change will display all current hosts in the history.
+This is correct as those hosts were present when the group was edited.
+But the information showing the hosts were added previously is missing.
+This is a limitation of the current implementation.
+
+
.. _Flask: https://flask.palletsprojects.com
.. _The Flask Mega-Tutorial: https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world
@@ -171,3 +196,4 @@ has the proper access (based on the network)::
.. _Elasticsearch: https://www.elastic.co/elasticsearch/
.. _RQ: https://python-rq.org
.. _alembic: https://alembic.sqlalchemy.org
+.. _SQLAlchemy-Continuum: https://sqlalchemy-continuum.readthedocs.io/en/latest/
--
GitLab