From b7c8809d228ffe4cd8d721b159fd0812d131327e Mon Sep 17 00:00:00 2001
From: Lance Wicks <lw@judocoach.com>
Date: Fri, 20 Oct 2017 22:50:55 +0100
Subject: [PATCH] Add basic migration documentation

A start on a migration document, in response to issuei on Test2::Suite
https://github.com/Test-More/Test2-Suite/issues/61
---
 lib/Test2/Manual.pm           |  5 +++
 lib/Test2/Manual/Migrating.pm | 70 +++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 lib/Test2/Manual/Migrating.pm

diff --git a/lib/Test2/Manual.pm b/lib/Test2/Manual.pm
index c1af204..117387b 100644
--- a/lib/Test2/Manual.pm
+++ b/lib/Test2/Manual.pm
@@ -28,6 +28,11 @@ writing new tools.
 
 The L<Test2::Manual::EndToEnd> is an overview of Test2 from load to finish.
 
+=head1 MIGRATING
+
+The L<TEST2::Manual::Migrating> is an short guide to assist when migrating from the
+Test:: family of modules to the TEST2:: modules.
+
 =head1 CONTRIBUTING
 
 The L<Test2::Manual::Contributing> POD is for people who want to contribute to
diff --git a/lib/Test2/Manual/Migrating.pm b/lib/Test2/Manual/Migrating.pm
new file mode 100644
index 0000000..2f56531
--- /dev/null
+++ b/lib/Test2/Manual/Migrating.pm
@@ -0,0 +1,70 @@
+=pod
+
+=head1 MIGRATING
+
+There are good reasons for migrating from the Test:: family of modules to
+the Test2:: modules. This document as well as describing some of these
+reaasons also aims to give some simple guidance on how to migrate your
+tests to Test2.
+
+=head1 EXAMPLE
+
+=head2 Test::
+
+	use strict;
+	use utf8;
+	use warnings;
+
+	use Test::Deep;
+	use Test::Fatal;
+	use Test::More;
+	use Test::Warnings;
+
+	binmode Test::More->builder->$_, ':encoding(UTF-8)'
+	    for qw/failure_output output/;
+
+	ok 1;
+
+	is $foo, $bar;
+
+	is_deeply $foo => [1..9];
+
+	like $foo, qr/A-Z/;
+
+	cmp_deeply $foo => {
+	    bar => ignore,
+	    baz => re(qr(A-Z)),
+	    qux => 1,
+	};
+
+	is warning { ... }, 'foo';
+
+	dies_ok { ... };
+
+	done_testing;
+
+=head2 Test2::
+
+	use Test2::V0;
+
+	ok 1;
+
+	is $foo, $bar;
+
+	is $foo => [1..9];
+
+	like $foo, qr/A-Z/;
+
+	like $foo => {
+	    baz => qr(A-Z),
+	    qux => 1,
+	};
+
+	is warning { ... }, 'foo';
+
+	ok dies { ... };
+
+	done_testing;
+
+=cut
+