[DB] Alembic: better documentation

alembic/README

@@ -6,6 +6,18 @@ Keep in mind that Alembic only handles SQLAlchemy models: tables created from
 Django ORM must be put out of Alembic sight. See [alembic:exclude] section in
 alembic.ini.
 
+To bootstrap Alembic where a gargantext database is already existing see
+below: TELL ALEMBIC TO NOT START FROM SCRATCH.
+
+
+USUAL WORKFLOW WITH ALEMBIC
+
+1. Make change to models in gargantext/models
+2. Autogenerate revision (see below GENERATE A REVISION)
+3. Manually check and edit revision file in alembic/versions
+4. Commit alembic revision (it should never be reverted)
+5. Commit changes in models (it can be reverted if needed)
+
 
 TELL ALEMBIC TO NOT START FROM SCRATCH
 
@@ -29,25 +41,25 @@ DOWNGRADE TO INITIAL DATABASE STATE
     alembic downgrade base
 
 
-GENERATE A NEW REVISION
+GENERATE A REVISION
 
-    alembic revision -m "Message for this migration"
+    alembic revision --autogenerate -m "Message for this migration"
 
     # A migration script is then created in alembic/versions directory. For
     # example alembic/versions/3adcc9a56557_message_for_this_migration.py
     # where 3adcc9a56557 is the revision id generated by Alembic.
     #
-    # This script must be edited to write the migration itself, mainly
-    # in `upgrade` and `downgrade` functions. See Alembic documentation for
-    # further details.
+    # Alembic should generate a script reflecting changes already made in
+    # models or database. However it is always a good idea to check it and edit
+    # it manually, Alembic is not always accurate and can't see all alterations.
+    # It should work with basic changes such as model or column creation. See
+    # http://alembic.zzzcomputing.com/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect
 
 
-GENERATE A REVISION FROM CURRENT STATE
+GENERATE AN EMPTY REVISION
 
-    alembic revision --autogenerate -m "Message for this migration"
+    alembic revision -m "Message for this migration"
 
-    # Alembic should generate a script reflecting changes already made in
-    # database. However it is always a good idea to check it and edit it
-    # manually, Alembic is not always accurate and can't see all alterations.
-    # It should work with basic changes such as model or column creation. See
-    # http://alembic.zzzcomputing.com/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect
+    # This script must be edited to write the migration itself, mainly
+    # in `upgrade` and `downgrade` functions. See Alembic documentation for
+    # further details.