From: Stevan Little Date: Sat, 21 Mar 2009 00:27:49 +0000 (-0400) Subject: - adding the contributing and delta pods X-Git-Tag: 0.72_01~64 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=600f7f852cf6bc7d0b2273d8b81cfc9e6689f29e;p=gitmo%2FMoose.git - adding the contributing and delta pods --- diff --git a/lib/Moose/Manual/Contributing.pod b/lib/Moose/Manual/Contributing.pod new file mode 100644 index 0000000..313a016 --- /dev/null +++ b/lib/Moose/Manual/Contributing.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +Moose::Manual::Contributing - How to get involved in Moose + +=head1 GETTING INVOLVED + +Moose is a pretty open project and we are always willing to accept +bug fixes, more tests and doc patches. Doing these things is as +simple as cloning a copy of the git repository and hacking away. All +we ask is that for any non-trivial code patches, you check with one +of the core developers before applying said patch. + +=head1 NEW FEATURES + +Moose already has a fairly large feature set and we are currently B +looking to add any new features to it. If you have an idea for a new +feature in Moose, you are invited instead to create a MooseX:: module +of it first. At this stage, no new features will even be considered for +addition into the core without first being vetted as a MooseX:: module. + +But worry not, Moose was built from the ground up with the idea of being +highly extensible and quite often the feature requests we see can be +implemented through a couple of small and well placed extensions. Try it, +it is much easier then you might think. + +=head1 TESTS, TESTS, TESTS + +If you write I code in Moose or Class::MOP, you B add tests +for that code. If you do not write tests then we cannot guarantee your +change will not be removed or altered at a later date. + +If your code change/addition is deep within the bowels of Moose/Class::MOP +and your test exercises this feature in a non-obvious way, please add some +comments either near the code in question or in the test so that others +know. + +=head1 BACKWARDS COMPATABILITY + +Change is inevitable and Moose is not immune to this. We do our best +to maintain backwards compatabilty, but we do not want the codebase +to become overburdened by this. This is not to say that we will +be frivolous with our changes, quite the opposite, it is more to say +that we are not afraid of change and will do our best to keep it as +painless as possible for the end user. + +The rule is that if you do something that is not backwards compatabile +you B do I one deprecation cycle (more if it is larger +change). For really larger or radical changes dev releases may be needed +as well (the core developers will decide on this on a case-per-case +basis). + +The preference with regard to deprecation is to warn loudly and often +so that users will have time to fix their usages. + +All backwards incompatible changes B be documented in +L and when possible should provide any useful +tips or workarounds to help smooth the transition process. + +=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 \ No newline at end of file diff --git a/lib/Moose/Manual/Delta.pod b/lib/Moose/Manual/Delta.pod new file mode 100644 index 0000000..b2fa98d --- /dev/null +++ b/lib/Moose/Manual/Delta.pod @@ -0,0 +1,306 @@ +=pod + +=head1 NAME + +Moose::Manual::Delta - Important Changes in Moose + +=head1 DESCRIPTION + +This attempts to document any important or noteworthy changes +in Moose both good or bad. While this does duplicate data from +the F file it aims to provide more details and when +possible fixes or workarounds as well. + +This document is a good way to keep up with important changes, +but it can also be useful in doing things like finding the lowest +version of Moose that supported a given feature, or as a helper +for people upgrading Moose versions and encountering issues. +So if you encounter a problem and have a solution but don't see +it documented here, or think I missed an important feature, then +please send us a patch. + +=head1 Version 0.73 + +Calling subtype with a name as the only argument is now an +exception. If you want an anonymous subtype do: + + my $subtype = subtype as 'Foo'; + +This is related to the changes in L. + +=head1 Version 0.72 + +A mutable class accepted Foo->new(undef) without complaint, +while an immutable class would blow up with an unhelpful +error. Now, in both cases we throw a helpful error +instead. + +This "feature" was originally added to allow for cases such +as this: + + my $args; + if (something()) { + $args = { ... }; + } + return My::Class->new($args); + +But it has been decided that this is bad form and you should +do what you mean more and not have Moose clean up for you. + +=head1 Version 0.71_01 + +Calling type or subtype without the sugar helpers (as, where, +message) is now deprecated. This means that code like this +will no longer work: + + use Moose::Util::TypeConstraints; + use Declare::Constraints::Simple -All; + + subtype 'ArrayOfInts' + => as 'ArrayRef' + => IsArrayRef(IsInt); + +Instead it must be changed to this: + + subtype('ArrayOfInts' => { + as => 'ArrayRef', + where => IsArrayRef(IsInt) + } + ); + +If you want to maintain backwards compat in your module then +you can just wrap it within a version test like so: + + if ($Moose::VERSION < 0.72) { + subtype 'ArrayOfInts' + => as 'ArrayRef' + => IsArrayRef(IsInt); + } + else { + subtype('ArrayOfInts' => { + as => 'ArrayRef', + where => IsArrayRef(IsInt) + } + ); + } + +=head1 Version 0.70 + +We no longer pass the meta-attribute object as a final +argument to triggers. This actually changed for inlined code a +while back, but the non-inlined version and the docs were +still out of date. + +Not sure how many people actually used this feature, but if +you did, the workaround is pretty simple. You just fetch the +attribute object from out of the C<$self> that is passed as +the first argument to trigger, like so: + +has 'foo' => ( + is => 'ro', + isa => 'Any', + trigger => sub { + my ($self, $value) = @_; + my $attr = $self->meta->find_attribute_by_name('foo'); + # ... + } +); + +=head1 Version 0.66 + +If you created a subtype and passed a parent that Moose didn't +know about, it simply ignored the parent. Now it automatically +creates the parent as a class type. This may not be what you +want, but is less broken than before. + +You could declare a name with subtype such as "Foo!Bar" that +would be allowed, but if you used it in a parameterized type +such as "ArrayRef[Foo!Bar]" it wouldn't work. We now do some +vetting on names created via the sugar functions, so that they +can only contain alphanumerics, ":", and ".". + +=head1 Version 0.65 + +Methods created via an attribute can now fulfill a C +declaration for a role. Honestly I don't know why I didn't make +this work originally, I was just insane or something. + +Stack traces from inlined code will now report its line and +file as being in your class, as opposed to in Moose guts. + +=head1 Version 0.62_02 + +When a class does not provide all of a role's required +methods, the error thrown now mentions all of the missing +methods, as opposed to just the first one found. + +Moose will no longer inline a constructor for your class +unless it inherits its constructor from Moose::Object, and +will warn when it doesn't inline. If you want to force +inlining anyway, pass "replace_constructor => 1" to +make_immutable. + +=head1 Version 0.62 + +Removed the (deprecated) make_immutable keyword. + +Removing an attribute from a class now also removes delegation +(handles) methods installed for that attribute. This is correct +behavior, but if you were wrongly relying on it you might get bit. + +=head1 Version 0.58 + +Roles now add methods by calling add_method, not +alias_method. They make sure to always provide a method +object, which will be cloned internally. This means that it is +now possible to track the source of a method provided by a +role, and even follow its history through intermediate roles. +This means that methods added by a role now show up when +looking at a class's method list/map. + +Parameter and Union args are now sorted, this makes Int|Str +the same constraint as Str|Int. Incoming type constraint strings +also are normalized to remove all whitespace differences. This is +all mostly just for internals and should not affect outside code. + +Moose::Exporter will no longer remove a subroutine that the +exporting package re-exports. Moose re-exports the +Carp::confess function, among others. The reasoning is that we +cannot know whether you have also explicitly imported those +functions for your own use, so we err on the safe side and +always keep them. + +=head1 Version 0.56 + +Moose::init_meta should now be called as a method. + +New modules for extension writers, Moose::Exporter and +Moose::Util::MetaRole. + +=head1 Version 0.55_01 + +Implemented metaclass traits (and wrote a recipe for it): + + use Moose -traits => 'Foo' + +This should make writing small Moose extensions a little +easier. + +=head1 Version 0.55 + +Fixed C to accept anon types just like C can. +So that you can do: + + coerce $some_anon_type => from 'Str' => via { ... }; + +=head1 Version 0.51 + +Added BUILDARGS, a new step in Moose::Object::new(). + +=head1 Version 0.49 + +Fixed how the C (ro|rw)> works with custom defined +reader, writer and accessor options. See the below table for +details: + + is => ro, writer => _foo # turns into (reader => foo, writer => _foo) + is => rw, writer => _foo # turns into (reader => foo, writer => _foo) + is => rw, accessor => _foo # turns into (accessor => _foo) + is => ro, accessor => _foo # error, accesor is rw + +=head1 Version 0.45 + +The C method modifiers now support regexp matching +of method names. NOTE: this only works for classes, it is currently not +supported in roles, but, ... patches welcome. + +The C keyword for roles now accepts the same array ref form that +Moose.pm does for classes. + +A trigger on a ro-attribute is no longer an error, as it's useful to +trigger off of the constructor. + +Subtypes of parameterizable types now are themselves parameterizable +types. + +=head1 Version 0.44 + +Fixed issue where DEMOLISHALL was eating the C<$@> values, and so not +working correctly, it still kind of eats them, but so does vanilla perl. + +=head1 Version 0.41 + +Inherited attributes may now be extended without restriction on the +type ('isa', 'does'). + +The entire set of Moose::Meta::TypeConstraint::* classes got refactored in +this release, chances are if you were relying on their internals you might +want to check on them. + +=head1 Version 0.40 + +Documenting the use of '+name' with attributes that come from recently +composed roles. It makes sense, people are using it, and so why not just +officially support it. + +The C method which now supports roles too. + +It is now possible to make anon-enums by passing 'enum' an ARRAY ref instead +of the $name => @values. + +=head1 Version 0.37 + +Added the 'make_immutable' keyword as a shortcut to calling make_immutable on +the meta object. However, this eventually gets removed again, but this is where +the trouble began. + +Making (init_arg => undef) work in Moose. This basically means "do not accept +a constructor parameter for this attribute". + +Making type errors use the assigned message, prior to this they didn't. + +=head1 Version 0.34 + +Moose is now a postmodern object system :) + +The Role system was completely refactored. It is 100% backwards compat, but the +internals are totaly changed. So if you relied on the internals then you might +want to check this one out. + +Added method exclusion and aliasing for Roles in this release. + +Added the L module. + +Passing a list of values to an accessor (which is only expecting one value) used +to be silently ignored, now it throws an error. + +=head1 Version 0.26 + +Added parameterized types and so did a pretty heavy refactoring of the type +constraint system. + +Better framework extendability and better support for "making your own Moose". + +=head1 Version 0.25 or before + +Honestly, you shouldn't be using versions of Moose that are this old, so many +bug fixes and speed improvements have been made you would be crazy to not +upgrade. + +Also, I am tired of going through the Changelog so I am stoping 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 \ No newline at end of file