Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
-=head1 Upgrading to Catalyst 5.90040
+=head1 Upgrading to Catalyst 5.90080
-This version of L<Catalyst> offers some support for using L<AnyEvent> and
-L<IO::Async> event loops in your application. In order to achieve this goal
-we needed to make some changes to the way the we finalize the HTTP response
-such that sloppy code that closed over $c and leaked memory will no longer
-work in some manner. For example you might accidently have:
+UTF8 encoding is now default. For temporary backwards compatibility, if this
+change is causing you trouble, you can disable it by setting the application
+configuration option to undef:
- $c->stash(my_model => sub { $c->model->find(shift) });
+ MyApp->config(encoding => undef);
-If you have old code that leaks memory in this way but otherwise seemed to
-work, it will no longer complete the response properly.
+But please consider this a temporary measure since it is the intention that
+UTF8 is enabled going forwards and the expectation is that other ecosystem
+projects will assume this as well. At some point you application will not
+correctly function without this setting.
-If you don't want to fix your code, you can force the old behavior with the
-global configuration key C<aggressively_close_writer_on_finalize_body>. This
-of course will still leave you with a leaky application and you lose the new
-event loop support, but your application will go back to completing its
-response output. For example:
+As of 5.90084 we've added two additional configuration flags for more selective
+control over some encoding changes: 'skip_body_param_unicode_decoding' and
+'skip_complex_post_part_handling'. You may use these to more selectively
+disable new features while you are seeking a long term fix. Please review
+CONFIGURATION in L<Catalyst>.
- package MyApp::Web;
+For further information, please see L<Catalyst::UTF8>
+
+A number of projects in the wider ecosystem required minor updates to be able
+to work correctly. Here's the known list:
+
+L<Catalyst::View::TT>, L<Catalyst::View::Mason>, L<Catalyst::View::HTML::Mason>,
+L<Catalyst::View::Xslate>, L<Test::WWW::Mechanize::Catalyst>
+
+You will need to update to modern versions in most cases, although quite a few
+of these only needed minor test case and documentation changes so you will need
+to review the changelog of each one that is relevant to you to determine your
+true upgrade needs.
+
+=head1 Upgrading to Catalyst 5.90060
+
+Starting in the v5.90059_001 development release, the regexp dispatch type is
+no longer automatically included as a dependency. If you are still using this
+dispatch type, you need to add L<Catalyst::DispatchType::Regex> into your build
+system.
+
+The standalone distribution of Regexp will be supported for the time being, but
+should we find that supporting it prevents us from moving L<Catalyst> forward
+in necessary ways, we reserve the right to drop that support. It is highly
+recommended that you use this last stage of deprecation to change your code.
+
+=head1 Upgrading to Catalyst 5.90040
+
+=head2 Catalyst::Plugin::Unicode::Encoding is now core
+
+The previously stand alone Unicode support module L<Catalyst::Plugin::Unicode::Encoding>
+has been brought into core as a default plugin. Going forward, all you need is
+to add a configuration setting for the encoding type. For example:
+
+ package Myapp::Web;
- use Moose;
use Catalyst;
- __PACKAGE__->config(
- name => 'MyApp::Web',
- enable_catalyst_header => 1,
- disable_component_resolution_regex_fallback => 1,
- aggressively_close_writer_on_finalize_body => 1,
- );
+ __PACKAGE__->config( encoding => 'UTF-8' );
- __PACKAGE__->setup;
+Please note that this is different from the old stand alone plugin which applied
+C<UTF-8> encoding by default (that is, if you did not set an explicit
+C<encoding> configuration value, it assumed you wanted UTF-8). In order to
+preserve backwards compatibility you will need to explicitly turn it on via the
+configuration setting. THIS MIGHT CHANGE IN THE FUTURE, so please consider
+starting to test your application with proper UTF-8 support and remove all those
+crappy hacks you munged into the code because you didn't know the Plugin
+existed :)
+
+For people that are using the Plugin, you will note a startup warning suggesting
+that you can remove it from the plugin list. When you do so, please remember to
+add the configuration setting, since you can no longer rely on the default being
+UTF-8. We'll add it for you if you continue to use the stand alone plugin and
+we detect this, but this backwards compatibility shim will likely be removed in
+a few releases (trying to clean up the codebase after all).
+
+If you have trouble with any of this, please bring it to the attention of the
+Catalyst maintainer group.
+
+=head2 basic async and event loop support
+
+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. Please see L<Catalyst::Response\write_fh> for more and for a
+basic example.
-See L<Catalyst::Component::ContextClosure> for help on how to close over the
-context safely, should you need to do this. See L<CatalystX::LeakChecker>
-and L<Catalyst::Controller::LeakTracker> for help if you want to solve your
-memory leak issues.
+We consider this feature experimental. We will try not to break it, but we
+reserve the right to make necessary changes to fix major issues that people
+run into when the use this functionality in the wild.
+
+=head1 Upgrading to Catalyst 5.90030
+
+=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.9
The engines that are built upon the various iterations of mod_perl,
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>
+should be seamless upgrades and will work using L<Plack::Handler::Apache1>
or L<Plack::Handler::Apache2> as required.
L<Catalyst::Engine::Apache2::MP19>, however, is no longer supported, as
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.
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).
+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:
sub action : Local {
my ( $self, $c ) = @_;
- $c->do_something;
+ $c->do_something;
}
1;
projects / catagits/Catalyst-Runtime.git / blobdiff