Add exception handling doc
Adding basic exception handling guideline to the HACKING.rst
Change-Id: I6c3bb2f5a7f7b8947193a005fc2fffe57ae0f0ba
diff --git a/HACKING.rst b/HACKING.rst
index 1db1e26..d69f935 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -157,6 +157,52 @@
kwarg2=dict_of_numbers)
+Exception Handling
+------------------
+According to the ``The Zen of Python`` the
+ ``Errors should never pass silently.``
+Tempest usually runs in special environment (jenkins gate jobs), in every
+error or failure situation we should provide as much error related
+information as possible, because we usually do not have the chance to
+investigate the situation after the issue happened.
+
+In every test case the abnormal situations must be very verbosely explained,
+by the exception and the log.
+
+In most cases the very first issue is the most important information.
+
+Try to avoid using ``try`` blocks in the test cases, both the ``except``
+and ``finally`` block could replace the original exception,
+when the additional operations leads to another exception.
+
+Just letting an exception to propagate, is not bad idea in a test case,
+ at all.
+
+Try to avoid using any exception handling construct which can hide the errors
+origin.
+
+If you really need to use a ``try`` block, please ensure the original
+exception at least logged. When the exception is logged you usually need
+to ``raise`` the same or a different exception anyway.
+
+Use the ``self.assert*`` methods provided by the unit test framework
+ the signal failures early.
+
+Avoid using the ``self.fail`` alone, it's stack trace will signal
+ the ``self.fail`` line as the origin of the error.
+
+Avoid constructing complex boolean expressions for assertion.
+The ``self.assertTrue`` or ``self.assertFalse`` will just tell you the
+single boolean, and you will not know anything about the values used in
+the formula. Most other assert method can include more information.
+For example ``self.assertIn`` can include the whole set.
+
+If the test case fails you can see the related logs and the information
+carried by the exception (exception class, backtrack and exception info).
+This and the service logs are your only guide to find the root cause of flaky
+issue.
+
+
Test Skips
----------
If a test is broken because of a bug it is appropriate to skip the test until