X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=66201a589af4c2158aa443fba624c429fd0cf469;hb=82e80cb1a3d0246b2e4ebc07f23599aadf9e8516;hp=c639b16ccbc75ae2824a900cea14764a40b0d7c3;hpb=8f61d649008a9894aed05cb4aa418da44cf710c8;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index c639b16..66201a5 100644
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -32,7 +32,19 @@ L<Moose> in your applications.
 
 =head2 Controller actions in Moose roles
 
-Declaring actions in Roles is currently unsupported.
+You can use L<MooseX::MethodAttributes::Role> if you want to declare actions
+inside Moose roles.
+
+=head2 Using Moose in Components
+
+The correct way to use Moose in a component in a both forward and backwards
+compatible way is:
+
+    package TestApp::Controller::Root;
+    use Moose;
+    BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
+
+See L<Components which inherit from Moose::Object before Catalyst::Component>.
 
 =head1 Known backwards compatibility breakages
 
@@ -104,21 +116,6 @@ with the C< BUILDARGS > method), will not work with Catalyst 5.80 as
 C<Catalyst::Component> inherits from C<Moose::Object>, and so C< @ISA > fails
 to linearize.
 
-The fix for this is to not inherit directly from C<Moose::Object>
-yourself. Having components which do not inherit their constructor from
-C<Catalyst::Component> is B<unsupported>, and has never been recommended,
-therefore you're on your own if you're using this technique. You'll need
-to detect the version of Catalyst your application is running, and deal
-with it appropriately.
-
-You will also see this issue if you do the following:
-
-    package TestApp::Controller::Example;
-    use Moose;
-    use base 'Catalyst::Controller';
-
-as C< use base > appends to @ISA.
-
 The correct way to use Moose in a component in a both forward and backwards
 compatible way is:
 
@@ -129,6 +126,13 @@ compatible way is:
 Note that the C< extends > declaration needs to occur in a begin block for
 L<attributes> to operate correctly.
 
+This way you do not inherit directly from C<Moose::Object>
+yourself. Having components which do not inherit their constructor from
+C<Catalyst::Component> is B<unsupported>, and has never been recommended,
+therefore you're on your own if you're using this technique. You'll need
+to detect the version of Catalyst your application is running, and deal
+with it appropriately.
+
 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.
@@ -140,6 +144,14 @@ attributes work as expected, and the BUILD method is called normally
 
 If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
 
+You will also see this issue if you do the following:
+
+    package TestApp::Controller::Example;
+    use Moose;
+    use base 'Catalyst::Controller';
+
+as C< use base > appends to @ISA.
+
 =head3 use Moose in MyApp
 
 Similar to the above, this will also fail:
@@ -205,7 +217,7 @@ been called, and will not call them again.
 
 Using this now causes infinite recursion between MyApp::setup and
 Catalyst::setup, due to other backwards compatibility issues related to how
-plugin setup works. Moose method modifiers like C<< before|after|around 'setup
+plugin setup works. Moose method modifiers like C<< before|after|around setup
 => sub { ... }; >> also will not operate correctly on the setup method.
 
 The right way to do it is this:
@@ -293,6 +305,43 @@ COMPONENT method in your @ISA.
 
 =head1 WARNINGS
 
+=head2 Actions in your application class
+
+Having actions in your application class will now emit a warning at application
+startup as this is deprecated. It is highly recommended that these actions are moved
+into a MyApp::Controller::Root (as demonstrated by the scaffold application
+generated by catalyst.pl). 
+
+This warning, also affects tests. You should move actions in your test,
+creating a myTest::Controller::Root, like the following example:
+
+    package MyTest::Controller::Root;
+
+    use strict;
+    use warnings;
+
+    use parent 'Catalyst::Controller';
+
+    __PACKAGE__->config(namespace => '');
+
+    sub action : Local {
+        my ( $self, $c ) = @_;
+        $c->do_something; 
+    }
+
+    1;
+
+=head2 ::[MVC]:: naming scheme
+
+Having packages called MyApp::[MVC]::XX is deprecated and can no longer be generated
+by catalyst.pl
+
+This is still supported, but it is recommended that you rename your application
+components to Model/View/Controller.
+
+A warning will be issued at application startup if the ::[MVC]:: naming scheme is
+in use.
+
 =head2 Catalyst::Base
 
 Any code using L<Catalyst::Base> will now emit a warning; this
@@ -352,7 +401,7 @@ to B<any> of the packages defined within that component.
 Calling the plugin method is deprecated, and calling it at run time is B<highly
 deprecated>.
 
-Instead you are recommended to use L< Catalyst::Model::Adaptor > or similar to
+Instead you are recommended to use L<Catalyst::Model::Adaptor> or similar to
 compose the functionality you need outside of the main application name space.
 
 Calling the plugin method will not be supported past Catalyst 5.81.