[OSSTEST PATCH 16/16] mg-schema-test-database: Add workflow doc comment

[Ian Jackson <ian.jackson@eu.citrix.com>]

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
---
v2: New patch
---
 mg-schema-test-database |   37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/mg-schema-test-database b/mg-schema-test-database
index 90a361b..d704950 100755
--- a/mg-schema-test-database
+++ b/mg-schema-test-database
@@ -34,7 +34,42 @@
 # NB that you can't drop a test database with these daemons running,
 # because Postgres will refuse to drop a database that anyone is
 # connected to.
-
+#
+#
+# Expected usage workflow:
+#
+#  1. Optionally, arrange for some hosts to be allocated to a suitable task
+#    OSSTEST_TASK=iwj@testing ./mg-allocate [-U ...] a-host
+#
+#  2. Create the test DB using the script
+#    ./mg-schema-test-database create [_SUFFIX] iwj@testing
+#
+#  3. Using the `export OSSTEST_CONFIG=' line printed by the above,
+#     play about in the test DB.  `a-host' will be `idle' in the test DB:
+#    OSSTEST_CONFIG=\
+#        /u/iwj/.xen-osstest/config:local-config.test-database_iwj \
+#     ./mg-allocate a-host
+#
+#  3a. Maybe run ./mg-schema-test-database daemons (if full-on queue
+#     running is desired).
+#
+#  3b. Meanwhile from the point of view of other users of the main DB,
+#     `a-host' is borrowed by a special task, but the rest of the main
+#     DB and its hosts can carry on.
+#
+#  3c. When talking to the real database, while you have a test DB set
+#     up, you have to set OSSTEST_DB_USEREAL_IGNORETEST eg
+#    OSSTEST_DB_USEREAL_IGNORETEST=osstest_test_iwj ./sg-run-job etc. etc.
+#     This is just to stop you operating on the real DB by mistake.
+#
+#  4. When you are done,
+#    ./mg-schema-test-database drop [_SUFFIX]
+#   This will throw away all of the information in the test DB.
+#
+#  5. OSSTEST_TASK=iwj@testing ./mg-allocate !a-host
+#   Hosts that were marked in the main DB as borrowed, are returned by
+#   mg-schema-test-database to the main DB task that previously owned
+#   them, but not freed.  So you need to explicitly free them.
 
 set -e -o posix ${OSSTEST_DEBUG:+-x}
 
-- 
1.7.10.4