Rewrite C3 chunk of Catalyst::Upgrading to hopefully be more clear

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Upgrading.pod

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index b19d5c0..608f426 100644 (file)
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -1,3 +1,7 @@
+=head1 NAME
+
+Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+
 =head1 Upgrading to Catalyst 5.80
 
 Most applications and plugins should run unaltered on Catalyst 5.80.
@@ -23,9 +27,23 @@ perl 5.10, and comes via L<Class::C3> for perl 5.8. This replaces L<NEXT>
 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:
 
@@ -38,13 +56,10 @@ Most common is the case of:
     package GoesBang;
     use base qw/Component1 Component2/;
 
-And the Catalyst plugin most often causing this, is
-L<Catalyst::Plugin::Sesssion::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
 
@@ -283,7 +298,7 @@ should change to using the public API, or, if you do not feel the public API
 adequately supports your use-case, please email the development list to
 discuss what API features you need so that you can be appropriately supported.
 
-=head2 Class naming to packages defined does not correspond.
+=head2 Class files with names that don't correspond to the packages they define
 
 In this version of Catalyst, if a component is loaded from disk, but no
 symbols are defined in that component's name space after it is loaded, this