advice on database and trigger/sp versioning

bin/dbsv-update.php

@@ -12,6 +12,9 @@
 	 * You should normally NOT call this script directly, but via dbupdate.php
 	 * (or something similar on a production system). This ensures that
 	 * everything takes place in the right order.
+	 *
+	 * See http://wiki.opencaching.de/index.php/Entwicklung/Datenbankversionierung
+	 * (German) and the comments in this file for further documentation.
 	 */
 
 	if (!isset($opt['rootpath']))
@@ -276,4 +279,17 @@
 		update_triggers();
 	}
 
+
+	// When adding new mutations, take care that they behave well if run multiple
+	// times. This improves robustness of database versioning.
+	//
+	// Please carefully decide if a new mutation relies on any triggers.
+	// If so, check if triggers need to be updated first - they may have changed
+	// since the last trigger update mutation (like #113) - or emulate the trigger
+	// behaviour by additional SQL statements which restore table consistency.
+	//
+	// Trigger updates can be directly included in a mutation, or can be done via
+	// a separate trigger update mutation (see #113 and maintain-113.inc.php).
+	// See also http://wiki.opencaching.de/index.php/Entwicklung/Datenbankversionierung.
+
 ?>

htdocs/doc/sql/stored-proc/maintain-113.inc.php

@@ -5,6 +5,12 @@
 
 		trigger and stored procedure definitions for DB version 113
 
+		This update includes ALL triggers and procedures, to make sure that we
+		have a defined starting point. Further updates need not to include
+		everything but may be restriced to functions which have actually changed.
+		However, it may be easier and safer to do a complete update. Hard disk
+		and repository space is cheap, and performance is no issue here.
+
 	***************************************************************************/
 
 	sql_dropFunction('distance');