From 08339c318b668bda3757f6c12a8af522e2462d25 Mon Sep 17 00:00:00 2001
From: Dmitry Tantsur <dtantsur@protonmail.com>
Date: Wed, 16 Sep 2020 17:37:36 +0200
Subject: [PATCH] Discourage using non-matching versions of Bifrost and Ironic

Also explain how to get a non-master version when using playbooks.

Change-Id: I1f6dd65fab0e2d6456746fbdc0b49fbe26c6d52d
---
 bifrost/cli.py               |  3 ++-
 doc/source/install/index.rst | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/bifrost/cli.py b/bifrost/cli.py
index 56b79634f..9115a75cf 100644
--- a/bifrost/cli.py
+++ b/bifrost/cli.py
@@ -182,7 +182,8 @@ def parse_args():
         'testenv', help='Prepare a virtual testing environment')
     testenv.set_defaults(func=cmd_testenv)
     testenv.add_argument('--release', default='master',
-                         help='release branch to use (master, ussuri, etc)')
+                         help='release branch to use (master, ussuri, etc), '
+                              'must match the release of bifrost.')
     testenv.add_argument('--count', type=int, default=2,
                          help='number of nodes to create')
     testenv.add_argument('--memory', type=int, default=3072,
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index fd197f27a..5b2e4c7eb 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -228,6 +228,16 @@ Additionally, the following parameters can be useful:
     .. warning::
        If using Keystone_, see :ref:`keystone-tls` for important notes.
 
+``--release``
+    If using a stable version of Bifrost, the corresponding version of Ironic
+    is usually detected from the git checkout. If it is not possible (e.g.
+    you're using Bifrost from a tarball), use this argument to provide
+    the matching version.
+
+    .. note::
+       Using Bifrost to install older versions of Ironic may work, but is not
+       guaranteed.
+
 See the built-in documentation for more details:
 
 .. code-block:: bash
@@ -451,6 +461,14 @@ below::
 
     $ ansible-playbook -K -vvvv -i inventory/target install.yaml -e cleaning_disk_erase=true
 
+If installing a stable release, you need to set two more parameters, e.g.::
+
+    -e git_branch=stable/train -e ipa_upstream_release=stable-train
+
+.. note::
+   Note the difference in format: git branch uses slashes, IPA release uses
+   dashes.
+
 After you have performed an installation, you can edit
 ``/etc/ironic/ironic.conf`` to enable or disable cleaning as desired.
 It is highly encouraged to utilize cleaning in any production environment.