another go at better async support

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

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index 48178fd..d1dd519 100644 (file)
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -2,6 +2,16 @@
 
 Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
 
+=head1 Upgrading to Catalyst 5.90040
+
+This version of L<Catalyst> offers some support for using L<AnyEvent> and
+L<IO::Async> event loops in your application.  These changes should work
+fine for most applications however if you are already trying to perform
+some streaming, minor changes in this area of the code might affect your
+functionality.
+
+  TDB: more on streaming, transfer encoding chunked, etc.
+
 =head1 Upgrading to Catalyst 5.9
 
 The major change is that L<Plack>, a toolkit for using the L<PSGI>
@@ -65,7 +75,7 @@ script is upgraded to use L<Catalyst::Script::HTTP>.
 If you were using L<Catalyst::Engine::CGI> there is no upgrade needed if your
 myapp_cgi.pl script is already upgraded to use L<Catalyst::Script::CGI>.
 
-=head2 Upgrading the Preforking Engine
+=head2 Upgrading Catalyst::Engine::HTTP::Prefork
 
 If you were using L<Catalyst::Engine::HTTP::Prefork> then L<Starman>
 is automatically loaded. You should (at least) change your C<Makefile.PL>
@@ -141,7 +151,6 @@ In the simplest case:
 
 becomes
 
-    MyCatalystApp->setup_engine('PSGI');
     my $app = MyCatalystApp->psgi_app(@_);
 
 B<NOT>:
@@ -157,6 +166,10 @@ any tests run via L<Catalyst::Test> will not be compatible with the new
 release, and will result in the development server starting, rather than
 the expected test running.
 
+B<NOTE:> If you are directly accessing C<< $c->req->env >> to get the PSGI
+environment then this accessor is moved to C<< $c->engine->env >>,
+you will need to update your code.
+
 =head2 Engines which are known to be broken
 
 The following engines B<DO NOT> work as of Catalyst version 5.9. The
@@ -211,6 +224,15 @@ This behavior has been removed, and now a 500 response will be returned
 to the test. This change standardizes behavior, so that local test
 requests behave similarly to remote requests.
 
+=head2 Regex dispatch type is deprecated.
+
+The Regex dispatchtype (L<Catalyst::DispatchType::Regex>) has been deprecated.
+
+You are encouraged to move your application to Chained dispatch (L<Catalyst::DispatchType::Chained>).
+
+If you cannot do so, please add a dependency to Catalyst::DispatchType::Regex to your application's
+Makefile.PL
+
 =head1 Upgrading to Catalyst 5.80
 
 Most applications and plugins should run unaltered on Catalyst 5.80.
@@ -220,7 +242,7 @@ been made which could cause incompatibilities. If your application or plugin
 is using deprecated code, or relying on side effects, then you could have
 issues upgrading to this release.
 
-Most issues found with pre-existing components have been easy to
+Most issues found with existing components have been easy to
 solve. This document provides a complete description of behavior changes
 which may cause compatibility issues, and of new Catalyst warnings which
 might be unclear.
@@ -278,7 +300,7 @@ replaces L<NEXT> with L<Class::C3::Adopt::NEXT>, forcing all components
 to resolve methods using C3, rather than the unpredictable dispatch
 order of L<NEXT>.
 
-This issue is characterised by your application failing to start due to an
+This issue manifests itself by your application failing to start due to an
 error message about having a non-linear @ISA.
 
 The Catalyst plugin most often causing this is
@@ -485,7 +507,7 @@ The following test demonstrates the problem:
     use Test::More;
     isnt(BaseClass->can('foo'), Child->can('foo'));
 
-=head2 Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors
+=head2 Extending Catalyst::Request or other classes in an ad hoc manner using mk_accessors
 
 Previously, it was possible to add additional accessors to Catalyst::Request
 (or other classes) by calling the mk_accessors class method.
@@ -512,6 +534,13 @@ The correct fix is to re-arrange your class's inheritance hierarchy so that the
 COMPONENT method you would like to inherit is the first (left-hand most)
 COMPONENT method in your @ISA.
 
+=head2 Development server relying on environment variables
+
+Previously, the development server would allow propagation of system
+environment variables into the request environment, this has changed with the
+adoption of Plack. You can use L<Plack::Middleware::ForceEnv> to achieve the
+same effect.
+
 =head1 WARNINGS
 
 =head2 Actions in your application class