[PATCH] docs: serial-tests are not deprecated, just discouraged (was: Re: bug#13478: Don't deprecate or remove 'serial-tests')

[Stefano Lattarini]

On 01/17/2013 07:26 PM, Stefano Lattarini wrote:
> On 01/17/2013 07:16 PM, Richard W.M. Jones wrote:
>>
>> For some reason this is marked as deprecated.
>>
>> This is bad: parallel tests are fine for tiny tests which use only a
>> little bit of memory.  However if your tests are very large and use a
>> lot of RAM then running them in parallel can cause them to fail
>> unnecessarily.
>>
>> The libguestfs test suite is exactly like this: parallel tests causes
>> it to fail because you end up running multiple parallel VMs.  Serial
>> tests is the right way to go for us.
>>
> This is a documentation problem, mostly (and my fault BTW, but let's move on).
> We should say that 'paralle-tests' is "encouraged", rather than saying that
> 'serial-tests' is "deprecated".  In fact, there are no plan to ever remove it,
> or even give runtime warnings upon its usage.
> 
Fixed by the patch below.  I'm thus closing this bug report.

Thanks,
  Stefano

---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< -----

>From e195e54eb13dd781413ffc617716b4cfe320c0b7 Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Fri, 18 Jan 2013 11:39:28 +0100
Subject: [PATCH] docs: serial-tests are not deprecated, just discouraged

We don't plan to remove support for them, nor to have the serial-tests
option give any kind of runtime warning, so don't alarm the users
still using serial tests with pointless "deprecation" or "obsolescence"
warnings.

Fixes automake bug#13478.

* doc/automake.texi: Adjust.
* THANKS: Update.

Signed-off-by: Stefano Lattarini <address@hidden>
---
 THANKS            |  1 +
 doc/automake.texi | 16 ++++++++++------
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/THANKS b/THANKS
index 58745e7..21ea373 100644
--- a/THANKS
+++ b/THANKS
@@ -331,6 +331,7 @@ Reuben Thomas                   address@hidden
 Rich Wales                      address@hidden
 Richard Boulton                 address@hidden
 Richard Dawe                    address@hidden
+Richard W.M. Jones              address@hidden
 Rob Savoye                      address@hidden
 Robert Bihlmeyer                address@hidden
 Robert Boehne                   address@hidden
diff --git a/doc/automake.texi b/doc/automake.texi
index ffc6819..3b830d5 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -319,7 +319,7 @@ Support for test suites
 Simple Tests

 * Scripts-based Testsuites::    Automake-specific concepts and terminology
-* Serial Test Harness::         Older (and obsolescent) serial test harness
+* Serial Test Harness::         Older (and discouraged) serial test harness
 * Parallel Test Harness::       Generic concurrent test harness

 Using the TAP test protocol
@@ -8806,7 +8806,7 @@ terminology)?

 @menu
 * Scripts-based Testsuites::    Automake-specific concepts and terminology
-* Serial Test Harness::         Older (and obsolescent) serial test harness
+* Serial Test Harness::         Older (and discouraged) serial test harness
 * Parallel Test Harness::       Generic concurrent test harness
 @end menu

@@ -8979,12 +8979,16 @@ by the tests, not the tests themselves.  Of course you 
can set
 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.

 @node Serial Test Harness
address@hidden Older (and obsolescent) serial test harness
address@hidden Older (and discouraged) serial test harness
 @cindex @option{serial-tests}, Using

address@hidden harness is obsolescent}, and kept for backward-compatibility
-reasons only.  The user is strongly advised to just use the parallel test
-harness instead (@pxref{Parallel Test Harness}).
+First, note that today the use of this harness is strongly discouraged in
+favour of the parallel test harness (@pxref{Parallel Test Harness}).
+Still, there are @emph{few} situations when the advantages offered by
+the parallel harness are irrelevant, and when test concurrency can
+even cause tricky problems.  In those cases, it might make sense to
+still use the serial harness, for simplicity and reliability (we still
+suggest trying to give the parallel harness a shot though).

 The serial test harness is enabled by the Automake option
 @option{serial-tests}. It operates by simply running the tests serially,
-- 
1.8.1.rc3.192.g2d0029e