Debbuging guidelines for validations-libs

The project documentation now contains a short guide to
issue reporting and pre diagnosis.

Short checklist is provided to help with data collection
before the report is submitted.

Signed-off-by: Jiri Podivin <jpodivin@redhat.com>
Change-Id: I0f1b28d69bb9d197ecc1ad63222bb74cb2c97c93

doc/source/debugging.rst

@@ -0,0 +1,57 @@
+.. debugging:
+
+=========
+Debugging
+=========
+
+Validations Framework needs a lot of moving parts to function properly.
+It is only given that sometimes things can go wrong.
+
+When that happens, you can save a lot of time by following several
+simple guidelines to debugging outlined bellow.
+
+
+Data collection
+---------------
+
+No matter what happened, it's not going to get fixed if nobody knows
+what it actually was. Therefore it is paramount that data collected
+about the issue are both accurate and comprehensive.
+
+It is especially important to collect information about the VF itself.
+
+If you aren't sure what you should look for, cosider the listed recommendations.
+The first four points deserve a special attention, as they constitute a bare minimumn
+needed to begin the issue diagnosis.
+
+* Note the system configuration. Information about VF packages,
+  validation target and user permissions should be given special attention.
+  As should be information about python interpreter used.
+* Record any output of the commands run. Up to and including the point
+  when the issue appeared.
+* Record presence and permissions of the '/var/log/validations' directory.
+* Record presence and permissions of the '/usr/share/ansible/validation-playbooks' directory.
+* Rerun the command with the same paramaters. Note the output.
+* Rerun the command with `--debug` parameter, while keeping the others unchanged.
+  Note the output.
+* Rerun the command in it's most basic form. That means no arguments, except for the bare minimum.
+  And note the output.
+
+
+Report submission
+-----------------
+
+We welcome all who come to our IRC channel. Whether they want to compliment us,
+or ask for help.
+Nevertheless, when it comes to more complex issues, it still pays to write a bug report.
+
+If you encounter problems with an upstream build of our code, you should post the problem,
+along with all information you have diligently collected, to the `Launchpad`_.
+
+Downstream bugs, on the other hand, are swallowed by `Bugzilla`_.
+
+It always pays to recheck the information you are putting in the report.
+Anyone can get lost in logs, and it's no shame to admit it.
+
+.. _Launchpad: https://bugs.launchpad.net/tripleo/+bugs?field.tag=validations
+.. _Bugzilla: https://bugzilla.redhat.com/buglist.cgi?component=validations-libs&product=Red%20Hat%20OpenStack

doc/source/index.rst

@@ -16,6 +16,7 @@ Contents
    readme
    contributing
    testing
+   debugging
    reference/index
 
 Indices and tables