From: Dave Rolsky Date: Sat, 21 Mar 2009 02:21:50 +0000 (-0500) Subject: Took a revision pass through this document X-Git-Tag: 0.72_01~58 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d85337ff2425a77264f50ddcb336f94462668103;p=gitmo%2FMoose.git Took a revision pass through this document --- diff --git a/lib/Moose/Manual/Contributing.pod b/lib/Moose/Manual/Contributing.pod index 4259957..8bf7ffe 100644 --- a/lib/Moose/Manual/Contributing.pod +++ b/lib/Moose/Manual/Contributing.pod @@ -6,57 +6,83 @@ 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. +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. + +Commit bits are given out freely. All we ask is that for any +non-trivial code patches, you check with one of the core developers +before applying said patch. + +Alternatively, you can make a new branch with your change and push it +back to the Moose git server, then ask a core dev to review your +branch. + +=head2 IRC and Email + +A B of Moose discussion happens on IRC. We have two channels on +irc.perl.org, #moose and #moose-dev. The former is much more active, +but the core developers pay attention to both channels. + +We also have a mailing list, moose@perl.org and all the core +developers read and respond to messages on that list. =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. +Moose already has a fairly large feature set and we are currently +B looking to add any major new features to it. If you have an +idea for a new feature in Moose, you are invited instead to create a +MooseX module first. + +At this stage, no new features will even be considered for addition +into the core without first being vetted as a MooseX module, unless +it is absolutely 100% impossible to implement the feature outside the +core. -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. +If you think it is 100% impossible, you're probably wrong. However, +your feature may need a small hook in the core, or a refactoring of +some core modules, and we are definitely open to that. + +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 you write I code for 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. -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. +We also greatly appreciate documentation to go with your changes, and +an entry in the Changes file. Make sure to give yourself credit! -=head1 BACKWARDS COMPATABILITY +=head1 BACKWARDS COMPATIBILITY -Change is inevitable and Moose is not immune to this. We do our best -to maintain backwards compatability, 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. +Change is inevitable and Moose is not immune to this. We do our best +to maintain backwards compatability, 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, just 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). +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. +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. +All backwards incompatible changes B be documented in +L. Mke sure to document any useful tips or +workarounds for the change in that document. =head1 AUTHOR @@ -71,4 +97,4 @@ 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 +=cut