Add note to explain how role versions can be adjusted

The OSA version can be overriden by users to move to a later
version of it (such as master).

This change adds cautionary note to README to explain what
they can do in this situation.

Change-Id: I3e4943c2c4af10001b07ffd289bd300bb5f80244
Signed-off-by: Fatih Degirmenci <fatih.degirmenci@ericsson.com>

2 files changed, 26 insertions, 1 deletions

diff --git a/xci/README.rst b/xci/README.rst
index b9909ed9..5ba34d5e 100644
--- a/xci/README.rst
+++ b/xci/README.rst
@@ -186,13 +186,17 @@ Once a working version is identified, the versions of the upstream components
 are then bumped in releng-xci repo.
 
 ==================
-XCI developer tips
+XCI Developer Tips
 ==================
 
+XCI Development Mode
+--------------------
+
 It is possible to run XCI in development mode, in order to test the
 latest changes. When deploying on this mode, the script will use the working
 directories for releng-xci/bifrost/OSA, instead of cloning the whole repositories
 on each run.
+
 To enable it, you need to export the different DEV_PATH vars:
 
 - export OPNFV_RELENG_DEV_PATH=/opt/releng-xci/
@@ -204,6 +208,23 @@ Please note the trailing slahses.
 This will cause the deployment to pick the development copies stored at the
 specified directories, and use them instead of cloning those on every run.
 
+Using a Different Version of OSA
+--------------------------------
+
+XCI pins OSA version based on upstream OSA CI & OPNFV XCI tests in order to have
+well tested/working versions for the developers, users, and more extensive CI loops,
+such as daily and weekly.
+
+If you change the OSA version by setting environment variables OPENSTACK_OSA_VERSION or
+manually in pinned-versions file, then it's likely to face incompatibilities with the
+dependent roles in ansible-role-requirements.yml file.
+
+If you run into this situation, then your best bet is to replace the XCI
+ansible-role-requirements.yml file with the upstream one from
+http://git.openstack.org/cgit/openstack/openstack-ansible/plain/ansible-role-requirements.yml.
+You also need to set OPNFV_RELENG_DEV_PATH as explained above in order for this file to be
+used throughout the deployment.
+
 ===========================================
 Limitations, Known Issues, and Improvements
 ===========================================
diff --git a/xci/config/pinned-versions b/xci/config/pinned-versions
index e1c110c6..c4e30d94 100755
--- a/xci/config/pinned-versions
+++ b/xci/config/pinned-versions
@@ -6,6 +6,10 @@
 # not work as expected. You can set the versions you want to use before running
 # the main script on your shell as shown on the examples below.
 #
+# If you intend to change OPENSTACK_OSA_VERSION, please ensure you update the
+# OSA ansible role versions as well. Take a look at README.rst file to see how
+# this can be done.
+#
 # It is important to be consistent between branches you use for OpenStack
 # projects OPNFV XCI uses.
 #