WIP DOC: Added documentation to versioning.

CHANGELOG.md

@@ -16,10 +16,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   whether the `feature_config` table has a particular value.
 * New `transactions` table. This is necessary for the ENTITY_VERSIONING feature
   and will replace the `transaction_log` table in the future.
-* ENTITY_VERSIONING (experimental)
+* Feature ENTITY_VERSIONING (experimental)
   Switch off this feature with `DELETE FROM feature_config WHERE
   _key="ENTITY_VERSIONING"` and switch on with `INSERT INTO feature_config
-  (_key, _value) VALUES ("ENTITY_VERSIONING", "ENABLED")` This feature comes
+  (_key, _value) VALUES ("ENTITY_VERSIONING", "ENABLED")`. This feature comes
   with a lot of additions to the API. E.g.
   * New `entity_version`.
   * All `*_data` tables have a new twin, the `archive_*_data` table, where all
@@ -28,9 +28,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * Additional `archive_isa` for the history entities' parents.
   * Additional `_iversion` column for the `reference_data` table for storing
     references to particular versions of an entity.
-  * New `setFileProperties` and `retrieveQueryTemplateDef` procedures which reduce server code and lets the
+  * New `setFileProperties` and `retrieveQueryTemplateDef` procedures which reduce server code and let the
     backend decide which tables to use. Also, this is necessary for the
-    versioning, because this procedure behaves differently depending on the
+    versioning, because these procedures behave differently depending on the
     ENTITY_VERSIONING feature being enabled or disabled.
   * Several functions and procedures for the interaction with the
     `entity_version` table and the `transactions` table. E.g.
@@ -42,7 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed ###
 
-* removed `getFile` procedure.
+* Removed `getFile` procedure.
 
 ### Deprecated ###
 
@@ -52,8 +52,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * POV with the 'name' property, e.g. `FIND ENTITY WITH name = something`
   [caosdb-server#51](https://gitlab.com/caosdb/caosdb-server/-/issues/51)
-- Fixed several bugs when an Entity inherits from itself (#18, caosdb-server #85).
-- Bug in `updateEntity.sql` (when updating the primary name without a prior call
+* Fixed several bugs when an Entity inherits from itself (#18, caosdb-server #85).
+* Bug in `updateEntity.sql` (when updating the primary name without a prior call
   to `deleteEntityProperties`). Same thing for `deleteEntity`.
 
 ### Security ###

README_SETUP.md

@@ -67,7 +67,7 @@ off for the procedures as described above. You should also empty the
 `entity_version` table because the `_fix_unversioned` procedure is only
 designed to cope with entities which do not have any versioning information at
 all. The already recorded versioning information is of course lost then! If you
-switch on the versioning at a some point in the future, the history begins anew
+switch on the versioning at some point in the future, the history begins anew
 with the then current version of the stored entities.
 
 ## Unit tests

patches/patch20200710-3.0.0-rc2/feature_config.sql

+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+-- Create a fresh `feature_config` table and the `is_feature_config` function.
 DROP TABLE IF EXISTS feature_config;
 CREATE TABLE feature_config (
     _key VARCHAR(255) PRIMARY KEY,

patches/patch20200710-3.0.0-rc2/patch.sh

@@ -5,6 +5,8 @@
 #
 # Copyright (C) 2018 Research Group Biomedical Physics,
 # Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+# Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
+# Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License as

patches/patch20200710-3.0.0-rc2/versioning.sql

+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+-- Create tables for versioning.
 DROP TABLE IF EXISTS archive_reference_data;
 DROP TABLE IF EXISTS archive_null_data;
 DROP TABLE IF EXISTS archive_text_data;
@@ -19,11 +40,11 @@ DROP TABLE IF EXISTS entity_version;
 DROP TABLE IF EXISTS transactions;
 
 CREATE TABLE transactions (
-  srid VARBINARY(255) PRIMARY KEY,
-  username VARBINARY(255) NOT NULL,
-  realm VARBINARY(255) NOT NULL,
-  seconds BIGINT UNSIGNED NOT NULL,
-  nanos INT(10) UNSIGNED NOT NULL
+  srid VARBINARY(255) PRIMARY KEY,  -- server request ID ?
+  username VARBINARY(255) NOT NULL, -- who did the transactions: username
+  realm VARBINARY(255) NOT NULL,    -- who did the transactions: realm
+  seconds BIGINT UNSIGNED NOT NULL, -- time of transaction: seconds
+  nanos INT(10) UNSIGNED NOT NULL   -- time of transaction: sub-second time resolution
 ) ENGINE=InnoDB;
 
 -- TODO remove ON DELETE CASCADE when feature is stable.