Introduce EXAMPLES section of documentation

Provide contextualized invocations of 'Porting/bisect.pl', e.g.:

* What was the problem for which we were bisecting?

* What, if anything, did we do prior to bisecting?

* What is the bug ticket for this problem?

Examples:

* Bisection with target 'miniperl'

* Bisecting failure on threaded builds only

* Example for '--crash' switch

* Failure of 'make' to complete build with specific C-compiler

1 files changed, 114 insertions, 0 deletions

diff --git a/Porting/bisect-runner.pl b/Porting/bisect-runner.pl
index d8e08c2b06..0ae5e5e0d6 100755
--- a/Porting/bisect-runner.pl
+++ b/Porting/bisect-runner.pl
@@ -844,6 +844,120 @@ Display the usage information and exit.
 
 =back
 
+=head1 EXAMPLES
+
+=head2 Code has started to crash under C<miniperl>
+
+=over 4
+
+=item * Problem
+
+Under C<make minitest> (but not under C<make test_harness>), F<t/re/pat.t> was
+failing to compile.  What was the first commit at which that compilation
+failure could be observed?
+
+=item * Solution
+
+Extract code from the test file at the point where C<./miniperl -Ilib -c> was
+showing a compilation failure.  Use that in bisection with the C<miniperl>
+target.
+
+    .../Porting/bisect.pl --target=miniperl --start=2ec4590e \
+        -e 'q|ace| =~ /c(?=.$)/; $#{^CAPTURE} == -1); exit 0;'
+
+=item * Reference
+
+L<GH issue 17293|https://github.com/Perl/perl5/issues/17293>
+
+=back
+
+=head2 Blead breaks CPAN on threaded builds only
+
+=over 4
+
+=item * Problem
+
+Tests in CPAN module XML::Parser's test suite had begun to fail when tested
+against blead in threaded builds only.
+
+=item * Solution
+
+Provide F<Configure>-style switch to bisection program.  Straightforward use
+of the C<--module> switch.
+
+    .../Porting/bisect.pl -Duseithreads \
+        --start=6256cf2c \
+        --end=f6f85064 \
+        --module=XML::Parser
+
+=item * Reference
+
+L<GH issue 16918|https://github.com/Perl/perl5/issues/16918>
+
+=back
+
+=head2 Point in time where code started to segfault is unknown
+
+=over 4
+
+=item * Problem
+
+User submitted code sample which when run caused F<perl> to segfault, but did
+not claim that this was a recent change.
+
+=item * Solution
+
+Used locally installed production releases of perl (previously created by
+F<perlbrew>) to identify the first production release at which the code would
+not compile.  Used that information to shorten bisection time.
+
+    .../perl Porting/bisect.pl \
+        --start=v5.14.4 \
+        --end=v5.16.3 \
+        --crash -- ./perl -Ilib /tmp/gh-17333-map.pl
+
+    $ cat gh-17333-map.pl
+
+    @N = 1..5;
+    map { pop @N } @N;
+
+=item * Reference
+
+L<GH issue 17333|https://github.com/Perl/perl5/issues/17333>
+
+=back
+
+=head2 When did perl start failing to build on a certain platform using C<g++> as the C-compiler?
+
+=over 4
+
+=item * Problem
+
+On NetBSD-8.0, C<perl> had never been smoke-tested using C<g++> as the
+C-compiler.  Once this was done, it became evident that changes in that
+version of the operating system's code were incompatible with some C<perl>
+source written long before that OS version was ever released!
+
+=item * Solution
+
+Bisection range was first narrowed using existing builds at release tags.
+Then, bisection specified the C-compiler via C<Configure>-style switch and
+used C<--test-build> to identify the commit which "broke" the build.
+
+    .../perl Porting/bisect.pl \
+        -Dcc=g++ \
+        --test-build \
+        --start=v5.21.6 \
+        --end=v5.21.7
+
+Then, problem was discussed with knowledgeable NetBSD user.
+
+=item * Reference
+
+L<GH issue 17381|https://github.com/Perl/perl5/issues/17381>
+
+=back
+
 =cut
 
 # Ensure we always exit with 255, to cause git bisect to abort.