Sod back-compat on the insane cases, start the upgrading documentation

diff --git a/TODO b/TODO
index 8715e8d..be81bbe 100644 (file)
--- a/TODO
+++ b/TODO
@@ -31,27 +31,11 @@ Known issues:
      - Catalyst::Plugin::DebugCookie
        - Conflict with each other: $c->config->{debug}->{foo} = 'bar'
          now breaks, unsure why..
-         
-      - Catalyst::Component::ACCEPT_CONTEXT - Having a COMPONENT method
-        after Catalyst::Component::COMPONENT used to work, and will still
-        delegate (and warn), but then NEXT::COMPONENT will not dtrt if you
-        re-dispatch again (NEXT would seemingly go back to the start?)..
-        See Reaction test suite for example of this happening.
-        FIXME - Also don't think this correctly delegates - $c appears 
-        missing.
 
   - Fix memory leaks (I already tried Devel::Leak::Object, but no joy).
 
-  -  In 5.70, you can have a component which doesn't inherit from ::Component, 
-     and has no new method, and it'll do the right thing for you. We should 
-     still support that, but warn for/deprecate it so it can go for 5.9X...
-     This obviously needs better tests :/
-
 Cleanups:
 
-  - Allow turning deprecated warnings off with use Catalyst 
-    qw/-NoDeprecationWarnings/
-
   - Update Test suite to not assume MyApp ISA Controller
     - After that set up attr handlers that will output helpful error messages 
       when you do it as well as how to fix it.
@@ -65,21 +49,19 @@ Cleanups:
 
 Documentation:
 
-   - extends in components with attributes must be inside a BEGIN block.
+   - Manual / Tutorial updates
 
-   - How to write Moosified Catalyst components.
+       - extends in components with attributes must be inside a BEGIN block.
 
-   - Manual / Tutorial updates
+       - How to write Moosified Catalyst components.
 
    - Fix the Roadmap to be less full of lies.
-
-   -  With 5.7 people did extends qw/Moose::Object Catalyst::Component/, now 
-      Catalyst::Component isa Moose::Object so now isa doesn't linearize 
-      anymore, docs of what doesn't work and why (rafl)
       
    - Document all other known failure cases / upgrade issues.
    
    - Tidy up / finish off incompatibility warnings etc.
+   
+   - Catalyst/Upgrading.pod
 
 Reported bugs:
 
@@ -94,7 +76,7 @@ Tests:
 
   - Moosified test application?
 
-  - Test warning from back-compat methods in Catalyst::Dispatcher
+  - Test & document warnings from back-compat methods in Catalyst::Dispatcher
   
-  - Test warnings from plugin method on Catalyst
+  - Test & document warnings from plugin method on Catalyst
 

diff --git a/lib/Catalyst/Component.pm b/lib/Catalyst/Component.pm
index 0c466fe..1301fc8 100644 (file)
--- a/lib/Catalyst/Component.pm
+++ b/lib/Catalyst/Component.pm
@@ -77,8 +77,10 @@ sub COMPONENT {
     if( my $next = $self->next::can ){
       my $class = blessed $self || $self;
       my ($next_package) = Class::MOP::get_code_info($next);
-      warn "There is a COMPONENT method resolving after Catalyst::Component in ${next_package}. This behavior is deprecated and will stop working in future releases.";
-      return $next->($self, $arguments);
+      warn "There is a COMPONENT method resolving after Catalyst::Component in ${next_package}.\n";
+      warn "This behavior can no longer be supported, and so your application is probably broken.\n";
+      warn "Your linearised isa hierarchy is: " . join(', ', mro::get_linear_isa($class)) . "\n";
+      warn "Please see perldoc Catalyst::Upgrading for more information about this issue.\n";
     }
     return $self->new($c, $arguments);
 }

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
new file mode 100644 (file)
index 0000000..8bc2209
--- /dev/null
+++ b/lib/Catalyst/Upgrading.pod
@@ -0,0 +1,84 @@
+=head1 Upgrading to Catalyst 5.80
+
+Work in progress
+
+=head1 Known backwards compatibility breakages.
+
+=head2 Catalyst::Plugin::Authentication
+
+You need at least version FIXME of Catalyst::Plugin::Authentication.
+
+=head2 Moose applications
+
+Applications made by early adopters, which say:
+
+    extends qw/Moose::Object Catalyst::Component/
+
+need the C<Moose::Object> removing to run with Catalyst 5.80, otherwise
+your Class' @ISA will not linearise with C3.
+
+rafl to fix this bit :)
+
+=head2 Components without new methods
+
+FIXME
+
+=head2 Components without COMPONENT methods
+
+FIXME
+
+=head2 __PACKAGE__->mk_accessor('meta');
+
+Won't work due to a limitation of L<MooseX::Emulate::Class::Accessor::Fast>
+
+FIXME
+
+=head2 Class::Data::Inheritable side effects
+
+FIXME
+
+=head2 Extending Catalyst::Request or other classes in an ad-hoc manor using mk_accessor
+
+FIXME
+
+=head2 require $class was successful but the package is not defined.
+
+FIXME Warning
+
+=head2 Components which inherit Catalyst::Component's COMPONENT method, who's new method does not return a true value.
+
+Previously if your new method returned a false value, then your class' configuration would be blessed into a hash on your behalf,
+and this would be returned from the COMPONENT method. This is no longer supported. You are not recommended to implement your own new method
+in components, instead, you should inherit the new method from Catalyst::Component, and use Moose's BUILD functionality
+to perform any construction work necessary for your sub-class.
+
+
+=head Methods in Catalyst::Dispatcher
+
+    Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,\n"
+    . "this will be removed in Catalyst 5.9X"
+
+FIXME
+
+=head2 Confused multiple inheritence with Catalyst::Component::COMPONENT
+
+Warning message:
+
+    There is a COMPONENT method resolving after Catalyst::Component 
+    in ${next_package}.
+    
+This means that one of the packages on the right hand side of 
+Catalyst::Component in your Class' inheritance hierarchy defines
+a COMPONENT method.
+
+Previously, Catalyst's COMPONENT method would delegate to the
+method on the right hand side, which could then delegate back again
+with NEXT. This (as it is insane), is no longer supported, as it
+makes no sense with C3 method dispatch order.
+
+Therefore the correct fix is to re-arrange your class' inheritance
+hierarchy so that the COMPONENT method you would like to inherit is
+the first COMPONENT method in your @ISA. 
+
+
+=cut