Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+=head2 Upgrading to Catalyst 5.90
+
+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
+L<Catalyst::Engine> this should be a straightforward upgrade for you. It was
+a design goal for this release to be as backwardly compatible as possible.
+However since L<Plack> is different from L<Catalyst::Engine> it would be
+possible that edge case differences would exist. Therefore we recommend care
+be taken with this upgrade and that testing should be greater than would be
+the case with a minor point update.
+
+It is highly recommended that you become familar with the L<Plack> ecosystem
+and documentation. Being able to take advantage of L<Plack> development and
+middleware is a major bonus to this upgrade.
+
+If you have created a custom subclass of L<Catalyst:Engine> you will need to
+convert it to be a subclass of L<Plack::Handler>.
+
+If you are using the L<Plack> engine, L<Catalyst::Engine::PSGI>, this new
+release supercedes that code.
+
+If you are using a subclass of L<Catalyst::Engine> that is aimed at nonstandard
+or internal / testing uses, such as L<Catalyst::Engine::Embeddable> you should
+still be able to continue using that engine.
+
+Advice for specific subclasses of L<Catalyst::Engine> follows:
+
+=head2 Upgrading the FastCGI Engine
+
+ TBD
+
+=head2 Upgrading the mod_perl / Apache Engines
+
+The three engines that are build upon the various iterations of mod_perl,
+L<Catalyst::Engine::Apache2::MP19>, L<Catalyst::Engine::Apache::MP13> and
+L<Catalyst::Engine::Apache2::MP20> should be seemless upgrades and will
+work using using L<Plack::Handler::Apache1> or L<Plack::Handler::Apache2>
+as required.
+
+=head2 Upgrading the HTTP Engine
+
+If you were using L<Catalyst::Engine::HTTP> (the default development server
+that comes with the L<Catalyst> distribution) you should now use...
+
+ TBD
+
+=head2 Upgrading the CGI Engine
+
+If you were using L<Catalyst::Engine::CGI> you should now use...
+
+ TBD
+
+=head2 Upgrading the Preforking Engine
+
+If you were using L<Catalyst::Engine::HTTP::Prefork> you should now use...
+
+ TBD
+
+=head2 Upgrading the Restarter Engines
+
+If you were using L<Catalyst::Engine::HTTP::Restarter> or
+L<Catalyst::Engine::HTTP::Restarter::Watcher> these are now longer part of the
+L<Catalyst> distribution. You should now use...
+
+ TBD
+
+=head2 Upgrading the PSGI Engine
+
+If you were using L<Catalyst::Engine::PSGI> this new release supercedes this
+engine in supporting L<Plack>. You should now do...
+
+ TBD
+
+=head2 Engines with unknown status
+
+The following engines have untested or unknown compatibility. Reports are
+highly welcomed:
+
+ Catalyst::Engine::Embeddable
+ Catalyst::Engine::XMPP2
+ Catalyst::Engine::SCGI
+ Catalyst::Engine::Mojo
+ Catalyst::Engine::Zeus
+ Catalyst::Engine::JobQueue::POE
+ Catalyst::Engine::Wx
+ Catalyst::Engine::Stomp
+ Catalyst::Engine::Server (Marked as Deprecated)
+ Catalyst::Engine::HTTP::POE (Marked as Deprecated)
+
+=head2 Engines known to not be compatible.
+
+If you are using one of the following L<Catalyst::Engine> subclasses, your
+application may require significant work after upgrading. We recommend you
+test heavily and sandbox your upgrade.
+
+ TBD
+
=head1 Upgrading to Catalyst 5.80
Most applications and plugins should run unaltered on Catalyst 5.80.
=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
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:
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.
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:
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:
=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
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.