X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FDelta.pod;h=22d32441bb1ed8b62e9abb5e36fce54ab7075522;hb=46aec47a553a7991d5a9e9faff176e9657777c44;hp=856b18ea47eae9e1bc2584e474ed7a360f5161bc;hpb=25f611086d46c31249d8369d54923bcc07a1e4b6;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Delta.pod b/lib/Catalyst/Delta.pod
index 856b18e..22d3244 100755
--- a/lib/Catalyst/Delta.pod
+++ b/lib/Catalyst/Delta.pod
@@ -1,8 +1,160 @@
-=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<Plack::Middleware::XSendfile> 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<Plack::Middleware::BufferedStreaming>
+or report specific problems to the dev team.
+
+Also, we have started migrating code in Catalyst to equivilent Plack
+Middleware when such exists and is correct to do so. 
+
+=head2 VERSION 5.90053
+
+We are now clarifying the behavior of log, plugins and configuration during
+the setup phase.  Since Plugins might require a log during setup, setup_log
+must run BEFORE setup_plugins.   This has the unfortunate side effect that
+anyone using the popular ConfigLoader plugin will not be able to supply
+configuration to custom logs since the configuration is not yet finalized
+when setup_log is run (when using ConfigLoader, which is a plugin and is
+not loaded until later.)
+
+As a workaround, you can supply custom log configuration directly into
+the configuration:
+
+    package MyApp;
+    use Catalyst;
+
+    __PACKAGE__->config(
+      my_custom_log_info => { %custom_args },
+    );
+
+    __PACKAGE__->setup;
+
+If you wish to configure the custom logger differently based on ENV, you can
+try:
+
+    package MyApp;
+
+    use Catalyst;
+    use Catalyst::Utils;
+
+    __PACKAGE__->config(
+      Catalyst::Utils::merge_hashes(
+        +{ my_custom_log_info => { %base_custom_args } },
+        +{ do __PACKAGE__->path_to( $ENV{WHICH_CONF}."_conf.pl") },
+      ),
+    );
+
+    __PACKAGE__->setup;
+
+Or create a standalone Configuration class that does the right thing.
+
+Basically if you want to configure a logger via Catalyst global configuration
+you can't use ConfigLoader because it will always be loaded too late to be of
+any use.  Patches and workaround options welcomed!
+
+=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<PSGI> 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<Plack>, and automatically gains support for any web server
+which a L<PSGI> 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<Catalyst::Upgrading> for notes about
+upgrading, especially if you are using an unusual deployment method.
+
+Documentation for how to take advantage of L<PSGI> can be found in
+L<Catalyst::PSGI>, and information about deploying your application
+has been moved to L<Catalyst::Manual::Deployment>.
+
+=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<Catalyst::Engine::HTTP::Prefork>
+
+This is now deprecated, see L<Catalyst::Upgrading>.
+
+=item L<Test::WWW::Mechanize::Catalyst>
+
+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<Catalyst::Upgrading> for a full description of how changes in the
 framework may affect your application.
@@ -25,7 +177,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 +230,9 @@ L<IO::Handle>.
 
 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 +249,7 @@ classes are better implemented as Moose roles.
 
 =item *
 
-L<MooseX::MethodAttributes::Inheritable> is used to contain action
+L<MooseX::MethodAttributes::Role::AttrContainer::Inheritable> is used to contain action
 attributes. This means that attributes are represented in the MOP, and
 decouples action creation from attributes.
 
@@ -118,7 +272,7 @@ Your application class is forced to become immutable at the end of compilation.
 
 =back
 
-=head2 Bug fixes
+=head3 Bug fixes
 
 =over