-=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
Moose already has a fairly large feature set, and we are currently
B<not> 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
+idea for a new feature in Moose, you are encouraged to create a
MooseX module first.
At this stage, no new features will even be considered for addition
core.
If you think it is 100% impossible, please come discuss it with us on IRC or
-via e-mail. However, your feature may need a small hook in the core, or a
+via e-mail. 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 than you might think.
+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 small
+extensions. Try it, it's much easier than you might think.
=head1 PEOPLE
=over
-=item Contributors - people creating a topic or branch
-
-You.
-
-If you have commit access, you can create a topic on the main Moose.git,
-otherwise either give us your SSH key or create your own clone of the
-L<git://git.moose.perl.org/Moose.git> repository or fork of the GitHub mirror.
-
-=item Core Committers - people reviewing and merging a branch
+=item Cabal - people who can release moose
-These people have worked with the Moose codebase for a while.
+These people are the ones who have co-maint on Moose itself and can create a
+release. They're listed under L<Moose/CABAL> in the Moose documentation. They
+are responsible for reviewing branches, and are the only people who are allowed
+to push to stable branches.
-They've been responsible for large features or branches and can help review
-your changes and apply them to the master branch using the basic
-L</APPROVAL WORKFLOW>.
+Cabal members are listed in L<Moose> and can often be found on irc in the
+L<irc://irc.perl.org/#moose-dev> channel.
-They are also fairly well versed in Git, in order to merge the branches with
-no mistakes (especially when the merge fails), and to provide advice to
-contributors.
+=item Contributors - people creating a topic or branch
-=item Cabal - people who can release moose
+You.
-These people are the ones who have co-maint on Moose itself and can create a
-release. They're listed under L<Moose/CABAL> in the Moose documentation. They
-merge from Master to Stable.
+The easiest way to submit a patch is to submit a pull request through Github.
+You can fork the Moose repository at C<git@github.com:moose/moose.git>. If you
+would prefer not to use Github, come talk to us at C<#moose> on C<irc.perl.org>
+and we can work something out.
=back
=over
-=item Stable (refs/heads/stable)
+=item stable/*
+
+The branch from which releases are cut. When making a new major release, the
+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
-The branch from which releases are cut. When making a new release, the
-release manager merges from master to stable. The stable branch is only
-updated by someone from the Cabal during a release.
+The main development branch. All new code should be written against this
+branch. This branch contains code that has been reviewed, and will be included
+in the next major release. Commits which are judged to not break backwards
+compatibility may be backported into C<stable> to be included in the next minor
+release.
-=item Master (refs/heads/master)
+=item rfc/*
-The branch for new development. This branch is merged into and branched from.
+Topic branches that are completed and waiting on review. A Cabal member will
+look over branches in this namespace, and either merge them to C<master> if
+they are acceptable, or move them back to a different namespace otherwise.
-=item Branches (refs/heads/*)
+=item topic/*
-Large community branches for big development "projects".
+Small personal branches that are still in progress. They can be freely rebased.
+They contain targeted features that may span a handful of commits. Any change
+or bugfix should be created in a topic branch.
-=item Topics (refs/heads/topic/*)
+=item attic/*
-Small personal branches that have been published for review, but can get
-freely rebased. Targeted features that may span a handful of commits.
+Branches which have been reviewed, and rejected. They remain in the repository
+in case we later change our mind, or in case parts of them are still useful.
-Any change or bugfix should be created in a topic branch.
+=item abandoned/*
+
+Topic branches which have had no activity for a long period of time will be
+moved here, to keep the main areas clean.
=back
+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 without checking with other developers first.
+
=head1 STANDARD WORKFLOW
# update your copy of master
git checkout -b topic/my-feature
# hack, commit, feel free to break fast forward
- git commit --amend # allowed
- git rebase --interactive # allowed
- git push --force origin topic/my_feature # allowed
-
-Then ask for a review/approval (see L</APPROVAL WORKFLOW>), and merge
-to master. If it merges cleanly and nobody has any objections, then it
-can be pushed to master.
-
-If it doesn't merge as a fast forward, the author of the branch needs to run
+ git commit --amend # allowed
+ git rebase --interactive # allowed
+ git push --force # allowed
+ # keep the branch rebased on top of master, for easy reviewing
git remote update
- git rebase origin/master # or merge
+ git rebase origin/master
+ git push --force
-and bring the branch up to date, so that it can be merged as a fast forward
-into master.
-
-No actual merging (as in a human resolving conflicts) should be done when
-merging into master, only from master into other branches.
-
-=head2 Preparing a topic branch
-
-Before a merge, a topic branch can be cleaned up by the author.
-
-This can be done using interactive rebase to combine commits, etc, or even
-C<git merge --squash> to make the whole topic into a single commit.
-
-Structuring changes like this makes it easier to apply git revert at a later
-date, and encourages a clean and descriptive history that documents what the
-author was trying to do, without the various hangups that happened while they
-were trying to do it (commits like "oops forgot that file" are not only
-unnecessary noise, they also make running things like git bisect or git revert
-harder).
+ # when finished, move the branch to the rfc/ namespace
+ git branch -m rfc/my-feature
+ git push
+ git push origin :topic/my-feature
-However, by far the biggest benefit is that the number of commits that go into
-master is eventually reduced, and they are simple and coherent, making it much
-easier for people maintaining branches to stay up to date.
+When your branch is completed, make sure it has been moved to the C<rfc/>
+namespace and is rebased on top of master, and ask for review/approval (see
+L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
+C<master>.
-All large changes should be documented in L<Moose::Manual::Delta>.
+No actual merging (as in a human resolving conflicts) should be done when
+merging into C<master>, only from C<master> into other branches.
=head1 APPROVAL WORKFLOW
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.
-The preferred way is to send a request to the mailing list for review/approval,
+B<your> responsibility to follow this process and advocate for your branch. The
+preferred way is to send a request to the mailing list for review/approval;
this allows us to better keep track of the branches awaiting approval and those
which have been approved.
=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.
+just doing a simple review. For especially simple patches (doc patches
+especially), committing directly to master is fine.
=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 F<cpan-stable-smolder> script in the moose-dev-utils
-repository.
+tested using the F<xt/author/test-my-dependents.t> test.
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.
+C<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 the bug and your
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 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.
+Ideally you will have run the F<test-my-dependents.t> 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. 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
=head1 RELEASE WORKFLOW
+ # major releases (including trial releases)
git checkout master
- # edit for final version bumping, changelogging, etc
- # prepare release (test suite etc)
- git commit
- git checkout stable
- git merge master # must be a fast forward
- git push both
- # ship & tag
-Development releases are made without merging into the stable branch.
+ # minor releases
+ git checkout stable/X.YY
+
+ # do final changelogging, etc
+ vim dist.ini # increment version number
+ git commit
+ 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 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 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
+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<dist.ini>.
=head1 EMERGENCY BUG WORKFLOW (for immediate release)
-Anyone can create the necessary fix by branching off of the stable branch:
+The stable branch exists for easily making bug fix releases.
git remote update
- git checkout -b topic/my-emergency-fix origin/stable
+ git checkout -b topic/my-emergency-fix origin/master
# hack
git commit
-Then a cabal member merges into stable:
+Then a cabal member merges into C<master>, and backports the change into
+C<stable/X.YY>:
- git checkout stable
+ git checkout master
git merge topic/my-emergency-fix
git push
+ git checkout stable/X.YY
+ git cherry-pick -x master
+ git push
# release
- git checkout master
- git merge stable
=head1 PROJECT WORKFLOW
(unfortunately Git will not allow C<my-project/foo> as a branch name if
C<my-project> is a valid ref).
-=head1 THE "PU" BRANCH
-
-To make things easier for longer lived branches (whether topics or projects),
-the 'pu' branch is basically what happens if you merge all of the branches and
-topics together with master.
-
-We can update this as necessary (e.g. on a weekly basis if there is merit),
-notifying the authors of the respective branches if their branches did not merge
-(and why).
-
-To update 'pu':
-
- git checkout pu
- git remote update
- git reset --hard origin/master
- git merge @all_the_branches
-
-If the merge is clean, 'pu' is updated with C<push --force>.
-
-If the merge is not clean, the offending branch is removed from
-C<@all_the_branches>, with a small note of the conflict, and we try again.
-
-The authors of the failed branches should be told to try to merge their branch
-into 'pu', to see how their branch interacts with other branches.
-
-'pu' is probably broken most of the time, but lets us know how the different
-branches interact.
-
=head1 BRANCH ARCHIVAL
Merged branches should be deleted.
-Failed branches may be kept, but consider moving to refs/attic/ (e.g.
-http://danns.co.uk/node/295) to keep git branch -l current.
+Failed branches may be kept, but should be moved to C<attic/> to differentiate
+them from in-progress topic branches.
-Any branch that could still realistically be merged in the future, even if it
-hasn't had work recently, should not be archived.
+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/>
+if you want to start working on it again.
=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 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>.
-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 DOCS, DOCS, DOCS
-We also greatly appreciate documentation to go with your changes, and
-an entry in the Changes file. Make sure to give yourself credit!
+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
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 compatible, you
-B<must> do I<at least> one deprecation cycle (more if it is larger change).
-For really larger or radical changes dev releases may be needed as well (the
-Cabal 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.
+Our policy for handling backwards compatibility is documented in more detail in
+L<Moose::Manual::Support>.
All backwards incompatible changes B<must> be documented in
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
-
-=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