-=pod
-
-=head1 NAME
+package Moose::Manual::Contributing;
-Moose::Manual::Contributing - How to get involved in Moose
-
-=head1 GETTING INVOLVED
+# ABSTRACT: How to get involved in Moose
-Moose is a pretty open project and we are always willing to accept bug
-fixes, more tests and documentation patches. Doing these things is as simple as
-cloning a copy of the Git repository and hacking.
+__END__
-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
+=pod
-A B<lot> 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.
+=head1 GETTING INVOLVED
-We also have a mailing list, moose@perl.org and all the core
-developers read and respond to messages on that list.
+Moose is an open project, and we are always willing to accept bug fixes,
+more tests, and documentation patches. Commit bits are given out freely, and
+the L</STANDARD WORKFLOW> is very simple. The general gist is: clone the Git
+repository, create a new topic branch, hack away, then find a committer to
+review your changes.
=head1 NEW FEATURES
-Moose already has a fairly large feature set and we are currently
+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
it is absolutely 100% impossible to implement the feature outside the
core.
-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.
+If you think it is 100% impossible, please come discuss it with us on IRC or
+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 small
+extensions. Try it, it's much easier than you might think.
+
+=head1 PEOPLE
+
+As Moose has matured, some structure has emerged in the process.
+
+=over
+
+=item Cabal - people who can release moose
+
+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.
+
+Cabal members are listed in L<Moose> and can often be found on irc in the
+L<irc://irc.perl.org/#moose-dev> channel.
+
+=item Contributors - people creating a topic or branch
+
+You.
+
+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
+
+=head1 BRANCH LAYOUT
+
+The repository is divided into several branches to make maintenance easier for
+everyone involved. The branches below are ordered by level of stability.
+
+=over
+
+=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 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 rfc/*
+
+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 topic/*
+
+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 attic/*
+
+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.
+
+=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 master
+ git pull --rebase
+
+ # create a new topic branch
+ 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 # allowed
+
+ # keep the branch rebased on top of master, for easy reviewing
+ git remote update
+ git rebase origin/master
+ git push --force
+
+ # when finished, move the branch to the rfc/ namespace
+ git branch -m rfc/my-feature
+ git push
+ git push origin :topic/my-feature
+
+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>.
+
+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
+
+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. 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.
+
+=over 4
+
+=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. For especially simple patches (doc patches
+especially), committing directly to master is fine.
-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.
+=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<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
+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
+test to the RT queue. Source control is not a bug reporting tool.
+
+=item New user-facing features.
+
+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 surprised if a new feature is rejected for the core.
+
+=item New internals features.
+
+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 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. 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
+defend your change.
+
+=back
+
+=head1 RELEASE WORKFLOW
+
+ # major releases (including trial releases)
+ git checkout master
+
+ # 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)
+
+The stable branch exists for easily making bug fix releases.
+
+ git remote update
+ git checkout -b topic/my-emergency-fix origin/master
+ # hack
+ git commit
+
+Then a cabal member merges into C<master>, and backports the change into
+C<stable/X.YY>:
+
+ git checkout master
+ git merge topic/my-emergency-fix
+ git push
+ git checkout stable/X.YY
+ git cherry-pick -x master
+ git push
+ # release
+
+=head1 PROJECT WORKFLOW
+
+For longer lasting branches, we use a subversion style branch layout, where
+master is routinely merged into the branch. Rebasing is allowed as long as all
+the branch contributors are using C<git pull --rebase> properly.
+
+C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
+only be done in topic branches. Committing to master is still done with the
+same review process as a topic branch, and the branch must merge as a fast
+forward.
+
+This is pretty much the way we're doing branches for large-ish things right
+now.
+
+Obviously there is no technical limitation on the number of branches. You can
+freely create topic branches off of project branches, or sub projects inside
+larger projects freely. Such branches should incorporate the name of the branch
+they were made off so that people don't accidentally assume they should be
+merged into master:
+
+ git checkout -b my-project--topic/foo my-project
+
+(unfortunately Git will not allow C<my-project/foo> as a branch name if
+C<my-project> is a valid ref).
+
+=head1 BRANCH ARCHIVAL
+
+Merged branches should be deleted.
+
+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/>
+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.
+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.
-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! Major changes or new
+user-facing features should also be documented in L<Moose::Manual::Delta>.
-We also greatly appreciate documentation to go with your changes, and
-an entry in the Changes file. Make sure to give yourself credit!
+=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
+Change is inevitable, and Moose is not immune to this. We do our best
to maintain backwards compatibility, but we do not want the code base
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 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 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.
+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>
-
-=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.
+L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
+for the change in that document.
=cut
projects / gitmo/Moose.git / blobdiff