turn waivers into a directory

Signed-off-by: Jiri Jaburek <comps@nomail.dom>

README.md

@@ -37,10 +37,14 @@ on Red Hat Enterprise Linux.
     - `1` (default) is `fail`, `error` and `warn`
     - `2` or greater to output everything
 
-- `CONTEST_WAIVERS`
-  - Specify a `conf/waiver-` suffix for a waiver file name inside `conf` to be
-    used for waiving results. Ie. `CONTEST_WAIVERS=upstream` to use
-    `conf/waivers-upstream`. Defaults to `released`.
+- `CONTEST_WAIVER_DIR`
+  - Specify a relative path to a waiver directory containing waiver files.
+    - The directory itself is traversed recursively (may contain further
+      sub-directories).
+  - All files and directories are read in a locale-specific sorted order,
+    and their contents combined to a final list of waiver rules.
+  - Files and directories starting with `.` are ignored.
+  - Defaults to `conf/waivers`.
 
 - `CONTEST_LEAVE_GUEST_RUNNING`
   - Set to `1` to break gurantees provided by `class Guest()`, that is make the

WAIVERS.md

@@ -1,9 +1,28 @@
 # Waiving known failures
 
+## Directory structure
+
+The files inside the [waivers directory](conf/waivers) are read in
+an alphanumeric order, including (sub)directories and any files inside them,
+forming a contiguous list of `<section>`s (as described below) from their
+contents.
+
+By convention, file names inside the waivers directory have specific meaning:
+
+- `unknown` - these are for waiving not-yet-known failures that we simply
+  don't want failing in daily runs while somebody investigates them
+- `long-term` - these are for investigated issues, which typically have
+  bugs or issues filed, and are waiting for a fix
+- `permanent` - these are never expected to be fixed, as they are a result
+  of the test infrastructure specifics, or other test or technology
+  limitations
+  - note that they may still disappear over time, ie. by dropping support
+    for an old OS release, which had the limitation
+
 ## Custom file format
 
-The [waivers file](conf/waivers) uses a custom file format to specify when
-a failure is expected.  
+The files inside the waivers directory use a custom file format to specify
+when a failure is expected.  
 This format consists of so-called "sections", optionally separated by any
 number of empty lines. Any lines beginning with `#` are skipped.