X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FDelta.pod;h=52a781db1ac9e4b5a80de263dd3cc5e547f6dfb0;hb=7605e87a6728e38c0b532430958bb52efb8139ff;hp=d30afedfff4cac48ca5a48b42e1e032fb6997322;hpb=27719606e64fe0434292ab905fe50280692df3f6;p=gitmo%2FMoose.git diff --git a/lib/Moose/Manual/Delta.pod b/lib/Moose/Manual/Delta.pod index d30afed..52a781d 100644 --- a/lib/Moose/Manual/Delta.pod +++ b/lib/Moose/Manual/Delta.pod @@ -1,14 +1,17 @@ -=pod +package Moose::Manual::Delta; + +# ABSTRACT: Important Changes in Moose -=head1 NAME +__END__ -Moose::Manual::Delta - Important Changes in Moose +=pod =head1 DESCRIPTION This documents any important or noteworthy changes in Moose, with a -focus on backwards. This does duplicate data from the F file, -but aims to provide more details and when possible workarounds. +focus on things that affect backwards compatibility. This does duplicate data +from the F file, but aims to provide more details and when possible +workarounds. Besides helping keep up with changes, you can also use this document for finding the lowest version of Moose that supported a given @@ -16,11 +19,188 @@ feature. If you encounter a problem and have a solution but don't see it documented here, or think we missed an important feature, please send us a patch. -=head1 NEXT +=head1 2.0100 + +=over 4 + +=item Hand-optimized type constraint code is deprecated in favor of inlining + +Moose allows you to provide a hand-optimized version of a type constraint's +subroutine reference. This version allows type constraints to generate inline +code, and you should use this inlining instead of providing a hand-optimized +subroutine reference. + +This affects the C sub exported by +L. Use C instead. + +This will start warning in the 2.0300 release. + +=head1 2.0002 + +=over 4 + +=item More useful type constraint error messages + +If you have L version 0.14 or higher installed, Moose's +type constraint error messages will use it to display the invalid value, rather +than just displaying it directly. This will generally be much more useful. For +instance, instead of this: + + Attribute (foo) does not pass the type constraint because: Validation failed for 'ArrayRef[Int]' with value ARRAY(0x275eed8) + +the error message will instead look like + + Attribute (foo) does not pass the type constraint because: Validation failed for 'ArrayRef[Int]' with value [ "a" ] + +Note that L can't be made a direct dependency at the +moment, because it uses Moose itself, but we're considering options to make +this easier. + +=back + +=head1 2.0000 + +=over 4 + +=item Roles have their own default attribute metaclass + +Previously, when a role was applied to a class, it would use the attribute +metaclass defined in the class when copying over the attributes in the role. +This was wrong, because for instance, using L in the class +would end up renaming all of the accessors generated by the role, some of which +may be being called in the role, causing it to break. Roles now keep track of +their own attribute metaclass to use by default when being applied to a class +(defaulting to Moose::Meta::Attribute). This is modifiable using +L by passing the C key to the +C option, as in: + + Moose::Util::MetaRole::apply_metaroles( + for => __PACKAGE__, + class_metaroles => { + attribute => ['My::Meta::Role::Attribute'], + }, + role_metaroles => { + applied_attribute => ['My::Meta::Role::Attribute'], + }, + ); + +=item Class::MOP has been folded into the Moose dist + +Moose and Class::MOP are tightly related enough that they have always had to be +kept pretty closely in step in terms of versions. Making them into a single +dist should simplify the upgrade process for users, as it should no longer be +possible to upgrade one without the other and potentially cause issues. No +functionality has changed, and this should be entirely transparent. + +=item Moose's conflict checking is more robust and useful + +There are two parts to this. The most useful one right now is that Moose will +ship with a C script, which can be run at any point to list the +modules which are installed that conflict with the installed version of Moose. +After upgrading Moose, running C should be sufficient +to ensure that all of the Moose extensions you use will continue to work. + +The other part is that Moose's C file will also specify the +conflicts under the C key. We are working with the Perl tool chain +developers to try to get conflicts support added to CPAN clients, and if/when +that happens, the metadata already exists, and so the conflict checking will +become automatic. + +=item Most deprecated APIs/features are slated for removal in Moose 2.0200 + +Most of the deprecated APIs and features in Moose will start throwing an error +in Moose 2.0200. Some of the features will go away entirely, and some will +simply throw an error. + +The things on the chopping block are: + +=over 8 + +=item * Old public methods in Class::MOP and Moose + +This includes things like C<< Class::MOP::Class->get_attribute_map >>, C<< +Class::MOP::Class->construct_instance >>, and many others. These were +deprecated in L 0.80_01, released on April 5, 2009. + +These methods will be removed entirely in Moose 2.0200. + +=item * Old public functions in Class::MOP + +This include C, C, and +the C constant. The first two were deprecated in 0.84, +and the last in 0.80. Class::MOP 0.84 was released on May 12, 2009. + +These functions will be removed entirely in Moose 2.0200. + +=item * The C and C option for role composition + +These were renamed to C<-alias> and C<-excludes> in Moose 0.89, released on +August 13, 2009. + +Passing these will throw an error in Moose 2.0200. + +=item * The old L API + +This include the C function, as well as passing the +C or any key ending in C<_roles> to C. This was +deprecated in Moose 0.93_01, released on January 4, 2010. + +These will all throw an error in Moose 2.0200. + +=item * Passing plain lists to C or C + +The old API for these functions allowed you to pass a plain list of parameter, +rather than a list of hash references (which is what C, C, +etc. return). This was deprecated in Moose 0.71_01, released on February 22, +2009. + +This will throw an error in Moose 2.0200. + +=item * The Role subtype + +This subtype was deprecated in Moose 0.84, released on June 26, 2009. + +This will be removed entirely in Moose 2.0200. + +=back + +=back + +=head1 1.21 + +=over 4 + +=item * New release policy + +As of the 2.0 release, Moose now has an official release and support policy, +documented in L. All API changes will now go through a +deprecation cycle of at least one year, after which the deprecated API can be +removed. Deprecations and removals will only happen in major releases. + +In between major releases, we will still make minor releases to add new +features, fix bugs, update documentation, etc. + +=back + +=head1 1.16 =over 4 -=item Native Traits +=item Configurable stacktraces + +Classes which use the L error class can now have +stacktraces disabled by setting the C env var to C. +This is experimental, fairly incomplete, and won't work in all cases (because +Moose's error system in general is all of these things), but this should allow +for reducing at least some of the verbosity in most cases. + +=back + +=head1 1.15 + +=over 4 + +=item Native Delegations In previous versions of Moose, the Native delegations were created as closures. The generated code was often quite slow compared to doing the same @@ -54,21 +234,42 @@ Perl builtins as much as possible. Finally, triggers are called whenever the value of the attribute is changed by a Native delegation. -These changes are only likely to break code in a few cases. If you have a -typed arrayref or hashref attribute where the type enforces a constraint on -the whole collection, this constraint will now be checked. It's possible that -code which previously ran without errors will now cause the constraint to -fail. However, presumably this is a good thing ;) +These changes are only likely to break code in a few cases. + +The inlining code may or may not preserve the original reference when changes +are made. In some cases, methods which change the value may replace it +entirely. This will break tied values. + +If you have a typed arrayref or hashref attribute where the type enforces a +constraint on the whole collection, this constraint will now be checked. It's +possible that code which previously ran without errors will now cause the +constraint to fail. However, presumably this is a good thing ;) If you are passing invalid arguments to a delegation which were previously -being ignore, these will now fail. +being ignored, these calls will now fail. -The other issue is the use of a trigger. If your code relied on the trigger -only being called for a regular writer, that may cause problems. +If your code relied on the trigger only being called for a regular writer, +that may cause problems. As always, you are encouraged to test before deploying the latest version of Moose to production. +=item Defaults is and default for String, Counter, and Bool + +A few native traits (String, Counter, Bool) provide default values of "is" and +"default" when you created an attribute. Allowing them to provide these values +is now deprecated. Supply the value yourself when creating the attribute. + +=item The C method + +Moose and Class::MOP have been cleaned up internally enough to make the +C method that you get by default optional. C and +C now can take an additional C<-meta_name> option, which +tells Moose what name to use when installing the C method. Passing +C to this option suppresses generation of the C method +entirely. This should be useful for users of modules which also use a C +method or function, such as L or L. + =back =head1 1.09 @@ -739,7 +940,7 @@ value) used to be silently ignored, now it throws an error. Added parameterized types and did a pretty heavy refactoring of the type constraint system. -Better framework extendability and better support for "making your own +Better framework extensibility and better support for "making your own Moose". =head1 0.25 or before @@ -751,17 +952,4 @@ crazy to not upgrade. Also, I am tired of going through the Changelog so I am stopping here, if anyone would like to continue this please feel free. -=head1 AUTHOR - -Stevan Little Estevan@iinteractive.comE - -=head1 COPYRIGHT AND LICENSE - -Copyright 2009 by Infinity Interactive, Inc. - -L - -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. - =cut