Document incompatibilities between 0.98 and 1.5.0

lib/Test/Builder.pm

@@ -2387,6 +2387,68 @@ Test::Builder->history->store_events >> is off, which it is by
 default.
 
 
+=head1 INCOMPATIBILITIES
+
+=head2 Between Test::Builder 0.98 and 1.5.0
+
+=head3 summary() and details() are only populated on request
+
+By default L<summary> and L<details> will throw an exception if you
+use them.  This is to keep memory usage down.  You can turn it on with
+C<< $history->store_events(1) >>, but we recommend you instead use the
+statistical methods of TB2::History instead.  See
+L<TB2::History/Statistics> and L<history> for more details.
+
+Here's an example of how you'd write code compatible across
+Test::Builder 0.98 and 1.5.0.
+
+    my $builder = Test::Builder->new;
+    if( $builder->can("history") ) {
+        my $history = $builder->history;
+        ...use TB2::History...
+    }
+    else {
+        ...use $builder->details or summary...
+    }
+
+=head3 Output handles are duplicated on first use
+
+Test::Builder will duplicate STDOUT and STDERR to make it safe for you
+to manipulate them as part of your test.  0.98 will duplicate them
+when the module is loaded, but 1.5.0 will duplicate them on first use.
+
+We recommend making any changes to the handles that you wish
+Test::Builder to see, such as turning on UTF8, as early as possible.
+
+We also recommend making any changes you I<don't> wish Test::Builder
+to see after the plan has been output.
+
+
+=head3 TAP version header
+
+1.5.0 uses TAP version 13 which will output a version header before
+anything else.
+
+    TAP version 13
+    1..1
+    ok 1
+
+If you have code which examines the output of a test, this may
+interfere.
+
+
+=head3 TAP end of test formatting
+
+The comment at the end of a failing test script has changed.
+Previously it was "Looks like you failed X test(s) of Y."  It is now
+"X test(s) of Y failed.".
+
+Other minor incompatibilities in the TAP comments will appear.  We
+recommend you do not rely on the TAP comments.  Instead use modules
+such as L<Test::Tester>, L<Test::Builder::Tester> or inspect the state
+of the test using the L<TB2::History> object.
+
+
 =head1 EXAMPLES
 
 CPAN can provide the best examples.  Test::Simple, Test::More,