From 58fcd8b668b457a920fac811d84f56dc961ad05a Mon Sep 17 00:00:00 2001
From: Ian Young <ian@iay.org.uk>
Date: Sun, 31 Jul 2016 11:43:54 +0100
Subject: [PATCH] Document property sources, add env mechanism.

Add the ability to use property files named according to the
deployment environment (dev, preprod, prod) as well as according
to the OS family.
---
 build.xml          | 44 ++++++++++++++++++++++++++++++++++++--------
 dev.properties     |  5 +++++
 preprod.properties |  5 +++++
 prod.properties    |  5 +++++
 4 files changed, 51 insertions(+), 8 deletions(-)
 create mode 100644 dev.properties
 create mode 100644 preprod.properties
 create mode 100644 prod.properties

diff --git a/build.xml b/build.xml
index 71aba569..4d4810d8 100644
--- a/build.xml
+++ b/build.xml
@@ -11,12 +11,19 @@
 -->
 <project default="echoproperties">
 
+    <!--
+        *******************************************
+        ***                                     ***
+        ***   P R O P E R T Y   S O U R C E S   ***
+        ***                                     ***
+        *******************************************
+    -->
+
     <!--
         os.family
 
-        Set a property representing the general kind of operating system
-        we're executing on.  We use this to decide which properties files
-        to load.
+        Distinguish between the general kind of operating systems
+        we could be executing on.
 
         Values: windows, macosx, linux, other.
     -->
@@ -31,19 +38,40 @@
     </condition>
     <property name="os.family" value="other"/>
 
+    <!--
+        env
+
+        Distinguish between different classes of deployment,
+        e.g., development vs. production.
+
+        Values: dev, preprod, prod
+
+        Defaults to "dev" here, but that can be overridden from the command
+        line, a Jenkins job, or in build.properties.
+    -->
+    <property name="env" value="dev"/>
+
     <!--
         External property files.
 
-        Pull in properties from external files.  Because Ant properties are
-        immutable, the first file containing a particular property sets the
-        final value, and any of these files can override a property defined in
-        this file.
+        Pull in properties from external files. Because Ant properties are
+        immutable, amy properties declared in this file should be regarded as
+        defaults, and will be overridden by any definitions in the following
+        locations:
+
+        * on the command line
+        * in a Jenkins job definition
+        * in any of the external files listed below
+
+        The first location specifying a particular property sets the final value.
 
         The build.properties file is not source controlled, and should be used
-        to override properties for a particular deployment.
+        to override properties for a particular deployment, or to include
+        credentials.
     -->
     <property file="build.properties"/>
     <property file="${os.family}.properties"/>
+    <property file="${env}.properties"/>
     <property file="default.properties"/>
 
     <!--
diff --git a/dev.properties b/dev.properties
new file mode 100644
index 00000000..31c0b6da
--- /dev/null
+++ b/dev.properties
@@ -0,0 +1,5 @@
+#
+# dev.properties
+#
+# Properties defined for the env=dev deployment environment.
+#
diff --git a/preprod.properties b/preprod.properties
new file mode 100644
index 00000000..8fe91d3e
--- /dev/null
+++ b/preprod.properties
@@ -0,0 +1,5 @@
+#
+# preprod.properties
+#
+# Properties defined for the env=preprod deployment environment.
+#
diff --git a/prod.properties b/prod.properties
new file mode 100644
index 00000000..aacf0d6b
--- /dev/null
+++ b/prod.properties
@@ -0,0 +1,5 @@
+#
+# prod.properties
+#
+# Properties defined for the env=prod deployment environment.
+#