Add a new FAQ entry for dev environments
Since it's pretty common to see blogposts recommending to mount /opt/stack
remotely or editing inline the code, adding some notes about the potential
risk of a reclone that could impact weeks of work.
Change-Id: I733d40b76fb02d8edf3719533fc8202547771871
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index 7793d8e..e6c1d6e 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -18,6 +18,57 @@
Your best choice is probably to choose a `distribution of OpenStack
<https://www.openstack.org/marketplace/distros/>`__.
+Can I use DevStack as a development environment?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sure, you can. That said, there are a couple of things you should note before
+doing so:
+
+- DevStack makes a lot of configuration changes to your system and should not
+ be run in your main development environment.
+
+- All the repositories that DevStack clones when deploying are considered
+ volatile by default and thus are subject to hard resets. This is necessary to
+ keep you in sync with the latest upstream, which is what you want in a CI
+ situation, but it can result in branches being overwritten and files being
+ removed.
+
+ The corollary of this is that if you are working on a specific project, using
+ the DevStack project repository (defaulted to ``/opt/stack/<project>``) as
+ the single master repository for storing all your work is not recommended.
+ This behavior can be overridden by setting the ``RECLONE`` config option to
+ ``no``. Alternatively, you can avoid running ``stack.sh`` to redeploy by
+ restarting services manually. In any case, you should generally ensure work
+ in progress is pushed to Gerrit or otherwise backed up before running
+ ``stack.sh``.
+
+- If you use DevStack within a VM, you may wish to mount a local OpenStack
+ directory, such as ``~/src/openstack``, inside the VM and configure DevStack
+ to use this as the clone location using the ``{PROJECT}_REPO`` config
+ variables. For example, assuming you're using Vagrant and sharing your home
+ directory, you should place the following in ``local.conf``:
+
+ .. code-block:: shell
+
+ NEUTRON_REPO=/home/vagrant/src/neutron
+ NOVA_REPO=/home/vagrant/src/nova
+ KEYSTONE_REPO=/home/vagrant/src/keystone
+ GLANCE_REPO=/home/vagrant/src/glance
+ SWIFT_REPO=/home/vagrant/src/swift
+ HORIZON_REPO=/home/vagrant/src/horizon
+ CINDER_REPO=/home/vagrant/src/cinder
+ HEAT_REPO=/home/vagrant/src/heat
+ TEMPEST_REPO=/home/vagrant/src/tempest
+ HEATCLIENT_REPO=/home/vagrant/src/python-heatclient
+ GLANCECLIENT_REPO=/home/vagrant/src/python-glanceclient
+ NOVACLIENT_REPO=/home/vagrant/src/python-novaclient
+ NEUTRONCLIENT_REPO=/home/vagrant/src/python-neutronclient
+ OPENSTACKCLIENT_REPO=/home/vagrant/src/python-openstackclient
+ HEAT_CFNTOOLS_REPO=/home/vagrant/src/heat-cfntools
+ HEAT_TEMPLATES_REPO=/home/vagrant/src/heat-templates
+ NEUTRON_FWAAS_REPO=/home/vagrant/src/neutron-fwaas
+ # ...
+
Why a shell script, why not chef/puppet/...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~