-=pod
+package Moose::Manual::Contributing;
+
+# ABSTRACT: How to get involved in Moose
-=head1 NAME
+__END__
-Moose::Manual::Contributing - How to get involved in Moose
+=pod
=head1 GETTING INVOLVED
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
=item Read+Write
-L<gitmo@git.moose.perl.org:Moose.git>
+gitmo@git.moose.perl.org:Moose.git
=back
are responsible for reviewing branches, and are the only people who are allowed
to push to stable branches.
+Cabal members are listed in L<Moose> and can often be found on irc in the
+L<irc://irc.perl.org/#moose-dev> channel.
+
=back
=head1 BRANCH LAYOUT
=item stable/*
The branch from which releases are cut. When making a new major release, the
-release manager makes a new C<stable/$version> branch at the current position
-of C<master>. For minor releases, patches will be committed to C<master>, and
-backported (cherry-picked) to the appropriate stable branch as needed. The
-C<stable> branch is only updated by someone from the Cabal during a release.
+release manager makes a new C<stable/X.YY> branch at the current position of
+C<master>. The version used in the stable branch should not include the last
+two digits of the version number.
+
+For minor releases, patches will be committed to C<master>, and
+backported (cherry-picked) to the appropriate stable branch as needed. A
+stable branch is only updated by someone from the Cabal during a release.
=item master
=back
-Larger, more long term branches can also be created in the root namespace (i.e.
-at the same level as master and stable). This is more appropriate if multiple
+Larger, longer term branches can also be created in the root namespace (i.e.
+at the same level as master and stable). This may be appropriate if multiple
people are intending to work on the branch. These branches should not be
-rebased.
+rebased without checking with other developers first.
=head1 STANDARD WORKFLOW
=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. Backwards incompatible changes should not be merged to master if there
+are strong objections from any cabal 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
git checkout master
# minor releases
- git checkout stable
+ git checkout stable/X.YY
- # edit for final version bumping, changelogging, etc
- # prepare release (test suite etc)
- perl-reversion -bump
- make manifest
+ # do final changelogging, etc
+ vim dist.ini # increment version number
git commit
- git branch stable/2.XXYY # only for non-trial major releases
- shipit # does not ship the tarball, but does everything else
-
- # non-trial releases
- cpan-upload ~/shipit-dist/Moose-2.XXYY.tar.gz
-
- # trial releases
- cd ~/shipit-dist
- mv Moose-2.XXYY.tar.gz Moose-2.XXYY-TRIAL.tar.gz
- cpan-upload Moose-2.XXYY-TRIAL.tar.gz
+ dzil release # or dzil release --trial for trial releases
+ git commit # to add the actual release date
+ git branch stable/X.YY # only for non-trial major releases
=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.
+Moose uses L<Dist::Zilla> to manage releases. Although the git repository comes
+with a C<Makefile.PL>, it is a very basic one just to allow the basic
+C<perl Makefile.PL && make && make test> cycle to work. In particular, it
+doesn't include any release metadata, such as dependencies. In order to get
+started with Dist::Zilla, first install it: C<cpanm Dist::Zilla>, and then
+install the plugins necessary for reading the C<dist.ini>:
+C<dzil authordeps | cpanm>.
+
+Moose 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<xt/author/test-my-dependents.t> test. This 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 use C<prove -b> and C<prove -I>, install the module, or fiddle
-with the C<PERL5LIB> environment variable, whatever makes you happy.
+arrange to have the new version of Moose in Perl's include path. You can use
+C<prove -b> and C<prove -I>, install the module, or fiddle with the C<PERL5LIB>
+environment variable, whatever makes you happy.
This test downloads each module from CPAN, runs its tests, and logs failures
and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
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.
+be noted in the conflicts list in the distribution's F<dist.ini>.
=head1 EMERGENCY BUG WORKFLOW (for immediate release)
git commit
Then a cabal member merges into C<master>, and backports the change into
-C<stable>:
+C<stable/X.YY>:
git checkout master
git merge topic/my-emergency-fix
git push
- git checkout stable
+ git checkout stable/X.YY
git cherry-pick -x master
git push
# release
Merged branches should be deleted.
-Failed branches may be kept, but should be to C<attic/> to differentiate them
-from in-progress topic branches.
+Failed branches may be kept, but should be moved to C<attic/> to differentiate
+them from in-progress topic branches.
Branches that have not been worked on for a long time will be moved to
C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
=head1 TESTS, TESTS, TESTS
-If you write I<any> code for Moose or Class::MOP, you B<must> 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,
-as there is nothing to confirm this is desired behavior.
+If you write I<any> code for Moose, you B<must> 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, as there is nothing to confirm this is desired
+behavior.
-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 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! Major changes or new
user-facing features should also be documented in L<Moose::Manual::Delta>.
+=head1 DOCS, DOCS, DOCS
+
+Any user-facing changes must be accompanied by documentation. If you're not
+comfortable writing docs yourself, you might be able to convince another Moose
+dev to help you.
+
+Our goal is to make sure that all features are documented. Undocumented
+features are not considered part of the API when it comes to determining
+whether a change is backwards compatible.
+
=head1 BACKWARDS COMPATIBILITY
Change is inevitable, and Moose is not immune to this. We do our best
L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
for the change in that document.
-=head1 AUTHOR
-
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
-
-Chris (perigrin) Prather
-
-Yuval (nothingmuch) Kogman
-
-Jesse Luehrs E<lt>doy at tozt dot netE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
=cut
projects / gitmo/Moose.git / blobdiff