Add some clarity to the first-time user experience
If a user follows the instructions in devtest, they'll first check out triple-incubator somewhere; then run scripts inside it, which (unknown to them) check out a different copy of tripleo-incubator into ~/.cache. This causes several surprises for the user: they'll be surprised to find that lots of disk images have been created, but they can't find those images. They'll be surprised when they edit scripts inside their original checkout, but those scripts are ignored when running the devtest_* scripts. They may well be surprised to find that none of the work they've done inside TRIPLEO_ROOT gets backed up, because most backup systems will ignore data under ~/.cache. This change moves the instructions about setting TRIPLEO_ROOT from devtest_variables.sh to the top of devtest.sh, so it's seen by the user before they do their initial checkout. Instructions for that checkout are tweaked so that the checkout goes into TRIPLEO_ROOT. The user should no longer be surprised by the location of the artifacts created by the scripts, as they'll have explicitly configured TRIPLEO_ROOT. As a side-effect, setting TRIPLEO_ROOT explicitly avoids the first-timer trap of trying to run devtest_setup.sh in the second step of devtest.html - prior to this change, this was implicitly relying on $TRIPLEO_ROOT/tripleo-incubator/scripts having devtest-setup.sh in it, which is true on the second run but not the first. This means we can get rid of some undocumented code that was working around this first-time scenario Some other improvements have been made. Now that we have a stable branch, the docs for checkout out a stable branch have been clarified with a real example, and split into their own section of the docs, labelled as being an optional step. Change-Id: I85e43df1cf1201b07131acf4985edfdf99cef30c
This commit is contained in:
parent
d87d326b23
commit
cd6c740ebd
|
@ -124,8 +124,41 @@ fi
|
|||
## username ALL = NOPASSWD: ALL
|
||||
##
|
||||
|
||||
## Stability Warning
|
||||
## -----------------
|
||||
## Initial Checkout
|
||||
## ----------------
|
||||
|
||||
## #. Choose a base location to put all of the source code.
|
||||
|
||||
## .. note::
|
||||
|
||||
## exports are ephemeral - they will not survive across new shell sessions
|
||||
## or reboots. If you put these export commands in ``~/.devtestrc``, you
|
||||
## can simply ``source ~/.devtestrc`` to reload them. Alternatively, you
|
||||
## can ``$TRIPLEO_ROOT/tripleo-incubator/scripts/write-tripleorc`` and then
|
||||
## source the generated tripleorc file.
|
||||
|
||||
## ::
|
||||
|
||||
## export TRIPLEO_ROOT=~/tripleo
|
||||
|
||||
## .. note::
|
||||
|
||||
## By default, devtest.sh uses ``~/.cache/tripleo`` for ``$TRIPLEO_ROOT``.
|
||||
## Unless you're planning to do a one-shot run of ``devtest.sh`` and never
|
||||
## look at the code installed or the artifacts generated, you should
|
||||
## set this value to something more convenient to you.
|
||||
|
||||
## #. Create the directory and check out the code
|
||||
|
||||
## ::
|
||||
|
||||
## mkdir -p $TRIPLEO_ROOT
|
||||
## cd $TRIPLEO_ROOT
|
||||
## git clone https://git.openstack.org/openstack/tripleo-incubator
|
||||
## cd tripleo-incubator
|
||||
|
||||
## Optional: stable branch
|
||||
## -----------------------
|
||||
|
||||
## Note that every effort is made to keep the published set of these instructions
|
||||
## updated for use with only the master branches of the TripleO projects. There is
|
||||
|
@ -137,11 +170,10 @@ fi
|
|||
|
||||
## If you wish to use the stable branches, you should instead checkout and clone
|
||||
## the stable branch of tripleo-incubator you want, and then build the
|
||||
## instructions yourself via::
|
||||
## instructions yourself. For instance, to create a local branch named
|
||||
## ``icehouse`` based on the upstream branch ``stable/icehouse``::
|
||||
|
||||
## git clone https://git.openstack.org/openstack/tripleo-incubator
|
||||
## cd tripleo-incubator
|
||||
## git checkout <stable-branch>
|
||||
## git checkout -b icehouse origin/stable/icehouse
|
||||
## tox -evenv python setup.py build_sphinx
|
||||
## # View doc/build/html/devtest.html in your browser and proceed from there
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@
|
|||
|
||||
## #. The devtest scripts require access to the libvirt system URI.
|
||||
## If running against a different libvirt URI you may encounter errors.
|
||||
## Export LIBVIRT_DEFAULT_URI to prevent devtest using qemu:///system
|
||||
## Export ``LIBVIRT_DEFAULT_URI`` to prevent devtest using qemu:///system
|
||||
## Check that the default libvirt connection for your user is qemu:///system.
|
||||
## If it is not, set an environment variable to configure the connection.
|
||||
## This configuration is necessary for consistency, as later steps assume
|
||||
|
@ -17,9 +17,9 @@
|
|||
|
||||
export LIBVIRT_DEFAULT_URI=${LIBVIRT_DEFAULT_URI:-"qemu:///system"}
|
||||
|
||||
## #. The vm's created by devtest will use a virtio network device by
|
||||
## #. The VMs created by devtest will use a virtio network device by
|
||||
## default. This can be overridden to use a different network driver for
|
||||
## interfaces instead, such as e1000 if required.
|
||||
## interfaces instead, such as ``e1000`` if required.
|
||||
## ::
|
||||
|
||||
export LIBVIRT_NIC_DRIVER=${LIBVIRT_NIC_DRIVER:-"virtio"}
|
||||
|
@ -35,35 +35,33 @@ export LIBVIRT_NIC_DRIVER=${LIBVIRT_NIC_DRIVER:-"virtio"}
|
|||
|
||||
export LIBVIRT_VOL_POOL=${LIBVIRT_VOL_POOL:-"default"}
|
||||
|
||||
## #. Choose a base location to put all of the source code.
|
||||
## #. Set ``TRIPLEO_ROOT``, if it wasn't already set. See note in :doc:`devtest`
|
||||
## for discussion on suggested values for ``TRIPLEO_ROOT``
|
||||
|
||||
## ::
|
||||
|
||||
## # exports are ephemeral - they will be lost between new shell
|
||||
## # sessions or reboots, and you will need to redo them. You can use
|
||||
## # $TRIPLEO_ROOT/tripleo-incubator/scripts/write-tripleorc to write
|
||||
## # them to a file ($TRIPLEO_ROOT/tripleorc by default) to be sourced
|
||||
## # later.
|
||||
## export TRIPLEO_ROOT=~/tripleo
|
||||
export TRIPLEO_ROOT=${TRIPLEO_ROOT:-~/.cache/tripleo} #nodocs
|
||||
export TRIPLEO_ROOT=${TRIPLEO_ROOT:-~/.cache/tripleo}
|
||||
|
||||
|
||||
## #. Nova tools will get installed in $TRIPLEO_ROOT/tripleo-incubator/scripts
|
||||
## - you need to add that to the PATH.
|
||||
## #. The TripleO tools will get (or have already been, if you followed the
|
||||
## suggestions in :doc:`devtest`) installed in
|
||||
## ``$TRIPLEO_ROOT/tripleo-incubator/scripts`` - you need to add that to the
|
||||
## ``$PATH``.
|
||||
|
||||
## ::
|
||||
|
||||
### --end
|
||||
# If devtest_setup.sh has never been run in this environment,
|
||||
# $TRIPLEO_ROOT/tripleo-incubator/scripts probably won't exist, so we can't
|
||||
# rely on being able to run devtest_setup.sh from there
|
||||
|
||||
if [ ! -e $TRIPLEO_ROOT ]; then
|
||||
export PATH=$(readlink -e $(dirname ${BASH_SOURCE[0]})):$PATH
|
||||
if [ ! -d "$TRIPLEO_ROOT/tripleo-incubator/scripts" ]; then
|
||||
echo ERROR: Cannot find "$TRIPLEO_ROOT/tripleo-incubator/scripts".
|
||||
echo " Please set TRIPLEO_ROOT to point to the directory which"
|
||||
echo " contains your tripleo-incubator checkout."
|
||||
exit 1
|
||||
fi
|
||||
### --include
|
||||
export PATH=$TRIPLEO_ROOT/tripleo-incubator/scripts:$PATH
|
||||
|
||||
## #. We now support Ironic as the baremetal deployment layer. To use it just
|
||||
## set USE_IRONIC=1. The default is still Nova Baremetal until we've had some
|
||||
## set ``USE_IRONIC=1``. The default is still Nova Baremetal until we've had some
|
||||
## time to identify any kinks in the process.
|
||||
## ::
|
||||
|
||||
|
|
Loading…
Reference in New Issue