Clarify mod_perl1 vs mod_perl2 vs mod_perl 1.99

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Upgrading.pod

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index f2b6a02..4fec7d3 100644 (file)
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -2,7 +2,7 @@
 
 Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
 
-=head1 Upgrading to Catalyst 5.90
+=head1 Upgrading to Catalyst 5.9
 
 The major change is that L<Plack> now replaces most of the subclasses of
 L<Catalyst::Engine>.  If you are using one of the standard subclasses of
@@ -39,13 +39,15 @@ enough to use L<Catalyst::Script::FastCGI>.
 =head2 Upgrading the mod_perl / Apache Engines
 
 The engines that are build upon the various iterations of mod_perl,
-L<Catalyst::Engine::Apache::MP13> and
-L<Catalyst::Engine::Apache2::MP20> should be seamless upgrades and will
-work using using L<Plack::Handler::Apache1> or L<Plack::Handler::Apache2>
-as required.  
+L<Catalyst::Engine::Apache::MP13> (for mod_perl 1, and Apache 1.x) and
+L<Catalyst::Engine::Apache2::MP20> (for mod_perl 2, and Apache 2.x)
+should be seamless upgrades and will work using using L<Plack::Handler::Apache1>
+or L<Plack::Handler::Apache2> as required.
 
 L<Catalyst::Engine::Apache2::MP19>, is however no longer supported, as Plack
-does not support mod_perl version 1.99
+does not support mod_perl version 1.99. This is unlikely to be a problem
+for anyone, as 1.99 was a brief beta-test release for mod_perl 2, and any users
+are encouraged to upgrade to a supported release of Apache 2 and mod_perl 2.
 
 =head2 Upgrading the HTTP Engine
 
@@ -61,11 +63,29 @@ myapp_cgi.pl script is already upgraded enough to use L<Catalyst::Script::CGI>.
 =head2 Upgrading the Preforking Engine
 
 If you were using L<Catalyst::Engine::HTTP::Prefork> then L<Starman>
-is automatically loaded.
+is automatically loaded. You should (at least) change your C<Makefile.PL>
+to depend on Starman.
 
-If you were customising your server script to pass options to the prefork engine,
-then this is no longer supported. The recommended route to implement this functionality
-is to write a simple .psgi file for your application, then use the L<plackup> utility.
+You can regenerate your C<myapp_server.pl> script with C<catalyst.pl>
+and implement a C<MyApp::Script::Server> class that looks like this:
+
+    package MyApp::Script::Server;
+    use Moose;
+    use namespace::autoclean;
+
+    extends 'CatalystX::Script::Server::Starman';
+
+    1;
+
+This takes advantage of the new script system, and adds a number of options to
+the standard server script as extra options are added by Starman.
+
+More information about these options can be seen at
+L<CatalystX::Script::Server::Starman/SYNOPSIS>.
+
+An alternate route to implement this functionality is to write a simple .psgi
+file for your application, then use the L<plackup> utility to start the
+server.
 
 =head2 Upgrading the PSGI Engine
 
@@ -132,7 +152,7 @@ the development server starting, rather than the expected test running.
 
 =head2 Engines which are known broken
 
-The following engines B<DO NOT> work as of Catalyst version 5.90. The core
+The following engines B<DO NOT> work as of Catalyst version 5.9. The core
 team is extremely happy to work with the developers and/or users of these
 engines to help them port to the new Plack/Engine system, however applications
 which are currently using these engines B<WILL NOT> run without modification
@@ -175,9 +195,9 @@ XXX FIXME
 
 See L<Catalyst::PSGI>.
 
-=head2 Tests in 5.89
+=head2 Tests in 5.9
 
-Tests should generally work the same in Catalyst 5.89, however there are some differences.
+Tests should generally work the same in Catalyst 5.9, however there are some differences.
 
 Previously, if using L<Catalyst::Test> and doing local requests (against a local server),
 if the application threw an exception then this exception propagated into the test.
@@ -556,7 +576,7 @@ is highly deprecated.
 The first time one of these methods is called, a warning will be emitted:
 
     Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
-    this will be removed in Catalyst 5.9X
+    this will be removed in Catalyst 5.9
 
 You should B<NEVER> be calling any of these methods from application code.