From ecc11af6fea164da03b10ab4476373a9e9ce60d0 Mon Sep 17 00:00:00 2001
From: Vitaliy Lotorev <lotorev@gmail.com>
Date: Sat, 2 Jan 2021 02:54:18 +0300
Subject: [PATCH] Document Python siblings handling for tox role

Brief overview how actually siblings are installed helps
proper usage of 'tox' role.

Change-Id: Id27c9c60a40e43c0e351849470ccb4d0d11739a3
---
 roles/tox/README.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/roles/tox/README.rst b/roles/tox/README.rst
index 2e0c06f82..4ed87391b 100644
--- a/roles/tox/README.rst
+++ b/roles/tox/README.rst
@@ -1,5 +1,24 @@
 Runs tox for a project
 
+This role overrides Python packages installed into tox environments with
+corresponding Zuul sibling projects and runs tox tests as follows:
+
+#. Create tox environments.
+#. Get Python sibling package names for sibling projects created by
+   Zuul (using ``required-projects`` job variable). Package names are
+   searched in following sources:
+
+   * ``setup.cfg`` of *pbr* projects,
+   * ``setup.py``,
+   * ``tox_package_name`` role variable.
+
+#. Remove sibling packages from tox environments.
+#. Create temporary constraints file, lines for sibling packages are
+   removed.
+#. Install sibling packages from Zuul projects into tox environments
+   with temporary constraints file.
+#. Run tox tests.
+
 **Role Variables**
 
 .. zuul:rolevar:: tox_environment