Doc, add new upgrading caveat, and start what works on Moose docs for lack of a bette...

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

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index 608f426..651c755 100644 (file)
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -18,8 +18,33 @@ or warnings which are now emitted is included below to help if you have problems
 If you think you have found an upgrade related issue which is not covered in
 this document, then please email the Catalyst list to discuss the problem.
 
+=head1 Moose features
+
+=head2 Application class roles.
+
+You can only apply method modifiers after the applications C<< ->setup >>
+method has been called. This means that modifiers will not work with methods
+which run during the call to C<< ->setup >>.
+
+=head2 Controller actions in Moose roles
+
+Is known to not work.
+
 =head1 Known backwards compatibility breakages.
 
+=head2 Applications in a single file.
+
+Applications must be in their own file, and loaded at compile time. This
+issue generally only affects the tests of cpan distributions. Defining an
+application inline in a block, and using plugins which supply a C< new >
+method, then using that application latter in tests, within the same file
+will cause your application to fail.
+
+This is due to the fact that Catalyst is inlining a new method on your
+application class allowing it to be compatible with Moose. The method used
+to do this changed in 5.80004 to avoid the possibility of reporting
+'Unknown Error' if your application failed to compile.
+
 =head2 Issues with Class::C3
 
 Catalyst 5.80 uses L<Algorithm::C3> method dispatch order. This is built into
@@ -34,7 +59,7 @@ The Catalyst plugin most often causing this, is
 L<Catalyst::Plugin::Session::Store::FastMmap> - if you are using this plugin
 and see issues, then please upgrade - and please try upgrading your plugins
 if you have this issue, as it has been fixed. Note that Makefile.PL in the
-distribution will warn about known incompatible components. 
+distribution will warn about known incompatible components.
 
 This issue can, however, be found in your own application - the only solution is
 to go through each base class of the class the error was reported against, until
@@ -99,14 +124,14 @@ compatible way is:
 Note that the C< extends > declaration needs to occur in a begin block for
 L<attributes> to operate correctly.
 
-You also don't get the L<Moose::Object> constructor, and therefore attribute 
-initialization will not work as normally expected. If you want to use Moose 
+You also don't get the L<Moose::Object> constructor, and therefore attribute
+initialization will not work as normally expected. If you want to use Moose
 attributes, then they need to be made lazy to correctly initialize.
 
 Note that this only applies if your component needs to maintain component
 backwards compatibility for Catalyst versions before 5.71001 - in 5.71001
 attributes work as expected, and the BUILD method is called normally
-(although BUILDARGS is not). 
+(although BUILDARGS is not).
 
 If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
 
@@ -126,7 +151,11 @@ etc) then the correct technique is:
 
     package MyApp;
     use Moose;
+    use Catalyst;
+
     extends 'Catalyst';
+
+    __PACKAGE__->config( name => 'MyApp' );
     __PACKAGE__->setup(qw/
         ConfigLoader
     /);
@@ -226,7 +255,7 @@ The following test demonstrates the problem:
 
     BaseClass->foo('base class');
     Child->foo('sub class');
-    
+
     use Test::More;
     isnt(BaseClass->can('foo'), Child->can('foo'));