Improve documentation on Moose::Util::TypConstraints "role_type" and "class_type"

[gitmo/Moose.git] / lib / Moose / Manual / Delta.pod

diff --git a/lib/Moose/Manual/Delta.pod b/lib/Moose/Manual/Delta.pod
index e9d42e9..52a781d 100644 (file)
--- a/lib/Moose/Manual/Delta.pod
+++ b/lib/Moose/Manual/Delta.pod
@@ -9,8 +9,9 @@ __END__
 =head1 DESCRIPTION
 
 This documents any important or noteworthy changes in Moose, with a
-focus on backwards. This does duplicate data from the F<Changes> 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<Changes> 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
@@ -18,7 +19,46 @@ 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<optimize_as> sub exported by
+L<Moose::Util::TypeConstraints>. Use C<inline_as> 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<Devel::PartialDump> 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<Devel::PartialDump> 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
 
@@ -44,6 +84,28 @@ C<role_metaroles> option, as in:
         },
     );
 
+=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<moose-outdated> 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<moose-outdated | cpanm> 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<META.json> file will also specify the
+conflicts under the C<x_conflicts> 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
@@ -58,7 +120,7 @@ The things on the chopping block are:
 
 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<Class::MOP> 0.80_01, release on April 5, 2009.
+deprecated in L<Class::MOP> 0.80_01, released on April 5, 2009.
 
 These methods will be removed entirely in Moose 2.0200.
 
@@ -104,6 +166,22 @@ This will be removed entirely in Moose 2.0200.
 
 =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<Moose::Manual::Support>. 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