[Catalyst-commits] r9928 - in Catalyst-Runtime/5.80/trunk: . lib/Catalyst

[t0m at dev.catalyst.perl.org]

Author: t0m
Date: 2009-04-28 22:56:07 +0100 (Tue, 28 Apr 2009)
New Revision: 9928

Modified:
   Catalyst-Runtime/5.80/trunk/Changes
   Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod
Log:
Rewrite C3 chunk of Catalyst::Upgrading to hopefully be more clear

Modified: Catalyst-Runtime/5.80/trunk/Changes
===================================================================
--- Catalyst-Runtime/5.80/trunk/Changes	2009-04-28 21:43:38 UTC (rev 9927)
+++ Catalyst-Runtime/5.80/trunk/Changes	2009-04-28 21:56:07 UTC (rev 9928)
@@ -21,6 +21,8 @@
         - Fix RT#43375 by sorting results before testing them (t0m)
         - Fixes for uri_for_action when using Catalyst::DispatchType::Regex
           + tests from RT#39369 (norbi)
+        - Partial rewrite and reoganisation of the C3 docs in
+          Catalyst::Upgrading based on feedback from kiffin (t0m)
 
 5.80002 2009-04-22 01:28:36
         - Fix CATALYST_DEBUG and MYAPP_DEBUG environment variables

Modified: Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod
===================================================================
--- Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod	2009-04-28 21:43:38 UTC (rev 9927)
+++ Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod	2009-04-28 21:56:07 UTC (rev 9928)
@@ -27,10 +27,24 @@
 with L<Class::C3::Adopt::NEXT>, forcing all components to resolve methods using
 C3, rather than the unpredictable dispatch order of L<NEXT>.
 
-To be able to do this, however, entails that the graph of superclasses for each
-class must be linearizable using the C3 algorithm. Unfortunately, when
-superclasses are being used as mixins, it is easy to get this wrong.
+This issue is characterised by your application failing to start due to an
+error message about having a non-linear @ISA.
 
+The Catalyst plugin most often causing this, is
+L<Catalyst::Plugin::Session::Store::FastMmap> - if you are using this plugin
+and see issues, then please upgrade - and please try upgrading your plugins
+if you have this issue, as it has been fixed. Note that Makefile.PL in the
+distribution will warn about known incompatible components. 
+
+This issue can, however, be found in your own application - the only solution is
+to go through each base class of the class the error was reported against, until
+you identify the ones in conflict, and resolve them.
+
+To be able to generate a linear @ISA, the list of superclasses for each
+class must be resolvable using the C3 algorithm. Unfortunately, when
+superclasses are being used as mixins (to add functionality used in your class),
+and with multiple inheritence, it is easy to get this wrong.
+
 Most common is the case of:
 
     package Component1; # Note, this is the common case
@@ -42,13 +56,10 @@
     package GoesBang;
     use base qw/Component1 Component2/;
 
-And the Catalyst plugin most often causing this, is
-L<Catalyst::Plugin::Session::Store::FastMmap> - if you are using this plugin
-and see issues, then please upgrade!
+Any situation like this will cause your application to fail to start.
 
-This can, however, be found in your own application - the only solution is to
-go through each base class of the class the error was reported against, until
-you identify the ones in conflict, and resolve them.
+Please see additional documentation about this issue, and how to resolve it in
+L<Class::C3::Adopt::NEXT>.
 
 =head2 Components which inherit from Moose::Object before Catalyst::Component