[tools 3/3] winetest/build-patterns: Add a header documenting the pattern pages.

Wed May 12 12:19:13 CDT 2021

Also tweak the descriptions for the pattern lists.

Signed-off-by: Francois Gouget <fgouget at codeweavers.com>
---
 winetest/build-patterns | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/winetest/build-patterns b/winetest/build-patterns
index 38bd7c041..240bf6912 100755
--- a/winetest/build-patterns
+++ b/winetest/build-patterns
@@ -1114,22 +1114,41 @@ sub write_patterns_page($$$)
 </head>
 <body>
 <div class="navbar"><a href="..">index</a> | Failure patterns: <a href="patterns.html">all</a> | <a href="patterns-tb-win.html">testbot windows</a> | <a href="patterns-tb-wine.html">testbot wine</a></div>
+
+<div class='testfile' id='summary'>
+<div class='updownbar'>$title</div>
+<p>The purpose of this page is to:</p>
+<ul>
+  <li>Help detect new test failures, that is test / Wine regressions.</li>
+  <li>Help diagnose failures by showing when they are specific to a set of Windows versions, a locale, a day of the week, etc.</li>
+</ul>
+<p>The patterns on this page read as follows:</p>
+<ul>
+  <li>Each line corresponds to a test configuration sorted by platform and tag name.</li>
+  <li>Test configurations with no failure for a given test are omitted from that test's pattern.</li>
+  <li>Each column corresponds to a WineTest build from oldest to newest.</li>
+  <li>Lines with a _N suffix are when WineTest was run more than once for a test configuration + build combination. They are rare and thus hang at the bottom of the pattern to not disrupt it.</li>
+  <li>Each cell is a single letter describing the result for that test. See the tooltips for a description. Click on the letter to go to that result page.</li>
+  <li>Each result is also color coded to make the patterns pop out. There is one color per type of result (crash , timeout, etc.), and one per number of failures (to help detect changes).</li>
+  <li>Failure modes that have not been seen before (test that newly crashes, new failure count, etc.) are highlighted, as well as the configuration names in which it appears.</li>
+  <li>Below the patterns is a line showing which builds have potentially related commits if any.
+</ul>
 EOF
 
     # Show the test units with recent failures first.
     # Also use these lists to link the test units to each other.
     my %lists = (
         recent   => {title => "Recent failures",
-                     desc => "have recent failures (that is failures that did not happen for the $patternbuilds oldest builds).",
+                     desc => "recently started failing (the $patternbuilds oldest builds had no failure).",
                      testnames => []},
         newmode  => {title => "New failure modes",
-                    desc => "failed in new ways in the $patternbuilds most recent builds.",
+                    desc => "failed in new ways in the $patternbuilds most recent builds (for instance they have more failures than before).",
                     testnames => []},
         regular  => {title => "Regular failures",
-                     desc => "had failures.",
+                     desc => "have failures... as usual :-(.",
                      testnames => []},
         old      => {title => "Old failures",
-                     desc => "had no failure in the most recent $patternbuilds builds. Fixed or just rare failures?",
+                     desc => "look like they are fixed: they had no failure in the most recent $patternbuilds builds but that may also just be a lucky streak.",
                      testnames => []},
     );
     foreach my $testname (sort keys %tests)
@@ -1202,7 +1221,7 @@ EOF
     }
 
     # Generate the lists index (and up test unit links)
-    print $html "<h1>$title</h1>\n";
+    print $html "<p>The patterns are grouped according to the likelyhood that they contain new failures:</p>\n";
     print $html "<ul>\n";
     my @listids = ("recent", "newmode", "regular", "old");
     my ($prevunit, $nolist) = ("", 1);
@@ -1211,13 +1230,14 @@ EOF
         my $list = $lists{$listid};
         my $count = @{$list->{testnames}};
         next if (!$count);
-        print $html "<li><a href='#$listid'>$count test units</a> $list->{desc}</li>\n";
+        print $html "<li><a href='#$listid'>$count tests</a> $list->{desc}</li>\n";
         $nolist = 0;
         $list->{prevunit} = $prevunit;
         $prevunit = $list->{testnames}->[-1];
     }
     print $html "<p>No failures. Don't change anything!</p>\n" if ($nolist);
     print $html "</ul>\n";
+    print $html "</div>\n";
 
     # Link the last test unit of each list to the first one of the next list
     my $nextunit;
-- 
2.20.1

