From 2b7ce5a8f37232c8cc28f86c6d659a0ec3f3f00b Mon Sep 17 00:00:00 2001
From: Dean Troyer <dtroyer@gmail.com>
Date: Thu, 10 Jan 2013 13:22:45 -0600
Subject: [PATCH] Add stackrc comments to HACKING

Change-Id: I46ff885184a2b5b71caca905c27f28d8b1304011
---
 HACKING.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/HACKING.rst b/HACKING.rst
index c4641fa051..6ad8c7e638 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -88,6 +88,30 @@ to be in the sub-script, such as testing for keystone being enabled in
 ``configure_swift()``.
 
 
+stackrc
+-------
+
+``stackrc`` is the global configuration file for DevStack.  It is responsible for
+calling ``localrc`` if it exists so configuration can be overridden by the user.
+
+The criteria for what belongs in ``stackrc`` can be vaguely summarized as
+follows:
+
+* All project respositories and branches (for historical reasons)
+* Global configuration that may be referenced in ``localrc``, i.e. ``DEST``, ``DATA_DIR``
+* Global service configuration like ``ENABLED_SERVICES``
+* Variables used by multiple services that do not have a clear owner, i.e.
+  ``VOLUME_BACKING_FILE_SIZE`` (nova-volumes and cinder) or ``PUBLIC_NETWORK_NAME``
+  (nova-network and quantum)
+* Variables that can not be cleanly declared in a project file due to
+  dependency ordering, i.e. the order of sourcing the project files can
+  not be changed for other reasons but the earlier file needs to dereference a
+  variable set in the later file.  This should be rare.
+
+Also, variable declarations in ``stackrc`` do NOT allow overriding (the form
+``FOO=${FOO:-baz}``); if they did then they can already be changed in ``localrc``
+and can stay in the project file.
+
 Documentation
 -------------