X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FDelta.pod;h=8281a0dbdf0d1a7d0da1244e6169e6cf1b39b553;hb=9629478d55a9a9a891ff3e12557aa334a9783c58;hp=856b18ea47eae9e1bc2584e474ed7a360f5161bc;hpb=25f611086d46c31249d8369d54923bcc07a1e4b6;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Delta.pod b/lib/Catalyst/Delta.pod index 856b18e..8281a0d 100755 --- a/lib/Catalyst/Delta.pod +++ b/lib/Catalyst/Delta.pod @@ -1,8 +1,112 @@ -=head1 Delta changes from 5.7 to 5.8 +=head1 NAME -This is an overview of the user visible changes in 5.8. +Catalyst::Delta - Overview of changes between versions of Catalyst -=head2 Deprecations +=head1 DESCRIPTION + +This is an overview of the user-visible changes to Catalyst between major +Catalyst releases. + +=head2 VERSION 5.90060+ + +We changed the way we return body content (from response) to whatever +Plack handler you are using (Starman, FastCGI, etc.) We no longer +always use the streaming interface for the cases when the body is a +simple scalar, object or filehandle like. In those cases we now just +pass the simple response on to the plack handler. This might lead to +some minor differences in how streaming is handled. For example, you +might notice that streaming starts using chunked encoding when running +on a server that supports that, or that previously missing headers +(possible content-length) might appear suddenly correct. Also, if you +are using middleware like L and are using +a filehandle that sets a readable path, your server might now correctly +handle the file (rather than as before where Catalyst would stream it +very likely very slowly). + +In other words, some things might be meaninglessly different and some +things that were broken codewise but worked because of Catalyst being +incorrect might suddenly be really broken. The behavior is now more +correct in that Catalyst plays better with features that Plack offers +but if you are making heavy use of the streaming interface there could +be some differences so you should test carefully (this is probably not +the vast majority of people). In particular if you are developing +using one server but deploying using a different one, differences in +what those server do with streaming should be noted. + +We also now more carefully distingush the different between a body set +to '' and a body that is undef. This might lead to situations where +again you'll get a content-length were you didn't get one before or +where a supporting server will start chunking output. If this is an +issue you can apply the middleware L +or report specific problems to the dev team. + +=head2 VERSION 5.9XXXX 'cataplack' + +The Catalyst::Engine sub-classes have all been removed and deprecated, +to be replaced with Plack handlers. + +Plack is an implementation of the L specification, which is +a standard interface between web servers and application frameworks. + +This should be no different for developers, and you should not have to +migrate your applications unless you are using a custom engine already. + +This change benefits Catalyst significantly by reducing the amount of +code inside the framework, and means that the framework gets upstream +bug fixes in L, and automatically gains support for any web server +which a L compliant handler is written for. + +It also allows you more flexibility with your application, and allows +the use of cross web framework 'middleware'. + +Developers are recommended to read L for notes about +upgrading, especially if you are using an unusual deployment method. + +Documentation for how to take advantage of L can be found in +L, and information about deploying your application +has been moved to L. + +=head3 Updated modules: + +A number of modules have been updated to pass their tests or not +produce deprecation warnings with the latest version of Catalyst. +It is recommended that you upgrade any of these that you are using +after installing this version of Catalyst. + +These extensions are: + +=over + +=item L + +This is now deprecated, see L. + +=item L + +Has been updated to not produce deprecation warnings, upgrade recommended. + +=item Catalyst::ActionRole::ACL + +Has been updated to fix failing tests (although older versions still +function perfectly with this version of Catalyst). + +=item Catalyst::Plugin::Session::Store::DBIC + +Has been updated to fix failing tests (although older versions still +function perfectly with this version of Catalyst). + +=item Catalyst::Plugin::Authentication + +Has been updated to fix failing tests (although older versions still +function perfectly with this version of Catalyst). + +=back + +=head1 PREVIOUS VERSIONS + +=head2 VERSION 5.8XXXX 'catamoose' + +=head3 Deprecations Please see L for a full description of how changes in the framework may affect your application. @@ -25,7 +129,7 @@ Below is a brief list of features which have been deprecated in this release: =back -=head2 New features +=head3 New features =head3 Dispatcher @@ -78,7 +182,9 @@ L. Added code method as an alias for C<< $res->status >> -=head2 Consequences of the Moose back end +=back + +=head3 Consequences of the Moose back end =over @@ -95,7 +201,7 @@ classes are better implemented as Moose roles. =item * -L is used to contain action +L is used to contain action attributes. This means that attributes are represented in the MOP, and decouples action creation from attributes. @@ -118,7 +224,7 @@ Your application class is forced to become immutable at the end of compilation. =back -=head2 Bug fixes +=head3 Bug fixes =over