Document tuple ordering differences as a possible cause of

regression test 'failures'.

diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 068b2c54eab9ae63668b132025fd0d560c0ffa8e..a4fdc5eed911934fe5e92e3069d93a053c5b9c18 100644 (file)
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   Regression Tests
@@ -248,7 +248,40 @@ SELECT * from iexit;
 
     
    
-    
+
+   
+    Tuple ordering differences
+      
+    
+You might see differences in which the same tuples are output in a
+different order than what appears in the expected file.  In most cases
+this is not, strictly speaking, a bug.  Most of the regression test
+scripts are not so pedantic as to use an ORDER BY for every single
+SELECT, and so their result tuple orderings are not well-defined
+according to the letter of the SQL spec.  In practice, since we are
+looking at the same queries being executed on the same data by the same
+software, we usually get the same result ordering on all platforms, and
+so the lack of ORDER BY isn't a problem.  Some queries do exhibit
+cross-platform ordering differences, however.
+    
+
+    
+Therefore, if you see an ordering difference, it's not something to
+worry about (unless the query does have an ORDER BY that your result
+is violating).  But please report it anyway, so that we can add an
+ORDER BY to that particular query and thereby eliminate the bogus
+failure in future releases.
+    
+
+    
+You might wonder why we don't ORDER all the regress test SELECTs to
+get rid of this issue once and for all.  The reason is that that would
+make the regression tests less useful, not more, since they'd tend
+to exercise query plan types that produce ordered results to the
+exclusion of those that don't.
+    
+   
+
    
     The <quote>random</quote> test
       

diff --git a/src/test/regress/README b/src/test/regress/README
index 7cfe65b2e55c68b01b0e2b493ddd0bdd16a8f438..f687c9aff3e6ef1a268aa0fc7581fe168fb1747e 100644 (file)
--- a/src/test/regress/README
+++ b/src/test/regress/README
@@ -166,6 +166,31 @@ statements where these problems occur are the following:
 SELECT * from street;
 SELECT * from iexit;
 
+Tuple ordering differences
+
+You might see differences in which the same tuples are output in a
+different order than what appears in the expected file.  In most cases
+this is not, strictly speaking, a bug.  Most of the regression test
+scripts are not so pedantic as to use an ORDER BY for every single
+SELECT, and so their result tuple orderings are not well-defined
+according to the letter of the SQL spec.  In practice, since we are
+looking at the same queries being executed on the same data by the same
+software, we usually get the same result ordering on all platforms, and
+so the lack of ORDER BY isn't a problem.  Some queries do exhibit
+cross-platform ordering differences, however.
+
+Therefore, if you see an ordering difference, it's not something to
+worry about (unless the query does have an ORDER BY that your result
+is violating).  But please report it anyway, so that we can add an
+ORDER BY to that particular query and thereby eliminate the bogus
+"failure" in future releases.
+
+You might wonder why we don't ORDER all the regress test SELECTs to
+get rid of this issue once and for all.  The reason is that that would
+make the regression tests less useful, not more, since they'd tend
+to exercise query plan types that produce ordered results to the
+exclusion of those that don't.
+
 The "random" test
 
 There is at least one case in the "random" test script that is