repository, create a new topic branch, hack away, then find a committer to
review your changes.
+Note that this document applies to both Moose and L<Class::MOP> development.
+
=head1 NEW FEATURES
Moose already has a fairly large feature set, and we are currently
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.
+it, it is much easier than you might think.
=head1 PEOPLE
=head1 APPROVAL WORKFLOW
-Moose is an open project but it also an increasingly important one, whose stability
-is depended on by many other modules. Therefore we need some basic set of
-criteria for accepting and approving branches into the core. What follows is the
-set of rough guidelines to be sure that all new code is properly vetted before it
-enters the core.
+Moose is an open project but it is also an increasingly important one. Many
+modules depend on Moose being stable. Therefore, we have a basic set of
+criteria for reviewing and merging branches. What follows is a set of rough
+guidelines that ensures all new code is properly vetted before it is merged to
+the master branch.
It should be noted that if you want your specific branch to be approved, it is
B<your> responsibility to follow this process and advocate for your branch.
=item Small bug fixes, doc patches and additional passing tests.
-These items don't really require approval beyond one of the core contributors just
-doing a simple review.
+These items don't really require approval beyond one of the core contributors
+just doing a simple review.
=item Larger bug fixes, doc additions and TODO or failing tests.
Larger bug fixes should be reviewed by at least one cabal member and should be
-tested using the smolder script to be sure no new issues were introduced.
+tested using the F<cpan-stable-smolder> script in the moose-dev-utils
+repository.
New documentation is always welcome, but should also be reviewed by a cabal
member for accuracy.
-TODO tests are basically feature requests, see our L</NEW FEATURES> section for
-more information on that. If your feature needs core support, create a topic/
-branch using the L</STANDARD WORKFLOW> and start hacking away.
+TODO tests are basically feature requests, see our L</NEW FEATURES> section
+for more information on that. If your feature needs core support, create a
+topic/ branch using the L</STANDARD WORKFLOW> and start hacking away.
-Failing tests are basically bug reports, you should find a core contributor and/or
-cabal member to see if it is a real bug, then submit it and your test to the RT
-queue. Source control is not a bug reporting tool.
+Failing tests are basically bug reports. You should find a core contributor
+and/or cabal member to see if it is a real bug, then submit the bug and your
+test to the RT queue. Source control is not a bug reporting tool.
=item New user-facing features.
-Anything that creates a new feature that is visible to a user needs to be approved
-by B<more then one> cabal member.
+Anything that creates a new user-visible feature needs to be approved by
+B<more than one> cabal member.
-Make sure you have reviewed L</NEW FEATURES> to be sure that you are following the
-guidelines. Do not be suprised if a new feature is rejected if it has not been either
-first vetted as a MooseX module or you cannot prove it is impossible to implement
-outside of core.
+Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
+the guidelines. Do not be surprised if a new feature is rejected for the core.
=item New internals features.
-New features for Moose internals are less restrictive then user facing features,
-but still require approval by B<at least one> cabal member.
+New features for Moose internals are less restrictive than user facing
+features, but still require approval by B<at least one> cabal member.
-Ideally you will have run a smolder script to be sure your not breaking any of the
-MooseX modules or causing any other unforseen havok. If you do this (rather then make
-us do it), it will only help to hasten your approval.
+Ideally you will have run the smolder script to be sure you are not breaking
+any MooseX module or causing any other unforeseen havoc. If you do this
+(rather than make us do it), it will only help to hasten your branch's
+approval.
=item Backwards incompatible changes.
-Anything that breaks backwards compatibility must be discussed by the cabal and
-agreed to by a majority of the members.
+Anything that breaks backwards compatibility must be discussed by the cabal
+and agreed to by a majority of the members.
-We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for Moose. If
-your changes break back-compat, you must be ready to discuss and debate your change.
+We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
+Moose. If your changes break back-compat, you must be ready to discuss and
+defend your change.
=back
git checkout stable
git merge master # must be a fast forward
git push both
- # ship & tag
+ shipit # does not ship the tarball, but does everything else
+ cpan-upload ~/shipit-dist/Moose-X.YZ.tar.gz
Development releases are made without merging into the stable branch.
+=head2 Release How-To
+
+Moose (and L<Class::MOP>) releases fall into two categories, each with their
+own level of release preparation. A minor release is one which does not
+include any API changes, deprecations, and so on. In that case, it is
+sufficient to simply test the release candidate against a few different
+different Perls. Testing should be done against at least two recent major
+version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
+available, you are encouraged to test them all. However, we do not put a lot
+of effort into supporting older 5.8.x releases.
+
+For major releases which include an API change or deprecation, you should run
+the F<cpan-stable-smolder> script from the L<moose-dev-utils
+repository|gitmo@git.moose.perl.org:moose-dev-utils.git>. This script tests a
+long list of MooseX and other Moose-using modules from CPAN. In order to run
+this script, you must arrange to have the new version of Moose and/or
+Class::MOP in Perl's include path. You can install the module, or fiddle with
+the C<PERL5LIB> environment variable, whatever makes you happy.
+
+The smolder script downloads each module from CPAN, runs its tests, and logs
+failures and warnings to a F<cpan-stable-smolder.log> file. If there are
+failures or warnings, please work with the authors of the modules in question
+to fix them. If the module author simply isn't available or does not want to
+fix the bug, it is okay to make a release.
+
+Regardless of whether or not a new module is available, any breakages should
+be noted in the conflicts list in the distribution's F<Makefile.PL>.
+
+Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the
+release goes smoothly. You are strongly encouraged to use this instead of
+doing the final release steps by hand.
+
=head1 EMERGENCY BUG WORKFLOW (for immediate release)
Anyone can create the necessary fix by branching off of the stable branch:
projects / gitmo/Moose.git / blobdiff