From a4a75cf22d810fbda95f3bf895636aa16b8786ea Mon Sep 17 00:00:00 2001
From: Michele Sollecito <michele.sollecito@gmail.com>
Date: Wed, 13 Jun 2018 13:25:23 +0100
Subject: [PATCH] [ENT-1893]: Db evolution documentation for CorDapp
 developers. (#986)

---
 docs/source/database-management.rst | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/source/database-management.rst b/docs/source/database-management.rst
index bf0a8bf773..9e4c4c9c0a 100644
--- a/docs/source/database-management.rst
+++ b/docs/source/database-management.rst
@@ -40,6 +40,11 @@ As a database migration framework, we use the open source library `Liquibase <ht
     Once such a change has been applied to the actual database, this fact is recorded in the database by the database migration library (see below),
     hence providing a mechanism to determine the 'version' of any given schema.
 
+.. warning::
+    Contract state tables created by CorDapps must remain backwards compatible between releases.
+    This means that they can evolve only by adding columns to them, and not by repurposing or deleting existing ones.
+    The reason for this is that this part of the database schema constitutes part of the CorDapp API, and third-party systems can integrate at the database level with Corda.
+    If you need to break compatibility, you have the option of creating a new version of the ``MappedSchema`` with new tables, but you would then have to write to both the old and the new version.
 
 About Liquibase
 ---------------
@@ -48,10 +53,10 @@ Liquibase is a tool that implements an automated, version based database migrati
 large number of databases. It works by maintaining a list of applied changesets. A changeset can be something very
 simple like adding a new column to a table. It stores each executed changeset with columns like id, author, timestamp,
 description, md5 hash, etc in a table called ``DATABASECHANGELOG``. This changelog table will be read every time a
-migration command is run to determine what changesets need to be executed. It represents the "version" of the database
-(the sum of the executed changesets at any point). Changesets are scripts written in a supported format (xml, yml,
+migration command is run to determine what change-sets need to be executed. It represents the "version" of the database
+(the sum of the executed change-sets at any point). Change-sets are scripts written in a supported format (xml, yml,
 sql), and should never be modified once they have been executed. Any necessary correction should be applied in a new
-changeset.
+change-set.
 
 For documentation around Liquibase see: `The Official website <http://www.liquibase.org>`_ and `Tutorial <https://www.thoughts-on-java.org/database-migration-with-liquibase-getting-started>`_.
 
@@ -75,9 +80,9 @@ Migration scripts structure
 Corda provides migration scripts in an XML format for its internal node and vault tables. CorDapps should provide
 migration scripts for the tables they manage. In Corda, ``MappedSchemas`` (see :doc:`api-persistence`) manage JPA
 Entities and thus the corresponding database tables. So ``MappedSchemas`` are the natural place to point to the
-changelog file(s) that contain the changesets for those tables. Nodes can configure which ``MappedSchemas`` are included
+changelog file(s) that contain the change-sets for those tables. Nodes can configure which ``MappedSchemas`` are included
 which means only the required tables are created. To follow standard best practices, our convention for structuring the
-changelogs is to have a "master" changelog file per ``MappedSchema`` that will only include release changelogs (see example below).
+change-logs is to have a "master" changelog file per ``MappedSchema`` that will only include release change-logs (see example below).
 
 Example:
 
@@ -267,7 +272,7 @@ production.
 
 .. warning:: A very important aspect to be remembered is that the CorDapp will have to work on all supported Corda databases.
    It is the responsibility of the developers to test the migration scripts and the CorDapp against all the databases.
-   In the future we will provide aditional tooling to assist with this aspect.
+   In the future we will provide additional tooling to assist with this aspect.
 
 When developing a new version of an existing CorDapp, depending on the changes to the ``PersistentEntities``, a
 changelog will have to be created as per the Liquibase documentation and the example above.