-=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 doc 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 a couple of small and well placed extensions. Try
-it, it is much easier then 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 TESTS, TESTS, TESTS
+=head1 PEOPLE
-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 Moose has matured, some structure has emerged in the process.
-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.
+=over
-We also greatly appreciate documentation to go with your changes, and
-an entry in the Changes file. Make sure to give yourself credit!
+=item Cabal - people who can release moose
-=head1 BACKWARDS COMPATIBILITY
+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.
-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.
+Cabal members are listed in L<Moose> and can often be found on irc in the
+L<irc://irc.perl.org/#moose-dev> channel.
-The rule is that if you do something that is not backwards compatabile
-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).
+=item Contributors - people creating a topic or branch
-The preference with regard to deprecation is to warn loudly and often
-so that users will have time to fix their usages.
+You.
-All backwards incompatible changes B<must> be documented in
-L<Moose::Manual::Delta>. Mke sure to document any useful tips or
-workarounds for the change in that document.
+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.
+
+=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.
-=head1 AUTHOR
+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.
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
+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.
-=head1 COPYRIGHT AND LICENSE
+=item New user-facing features.
-Copyright 2009 by Infinity Interactive, Inc.
+Anything that creates a new user-visible feature needs to be approved by
+B<more than one> cabal member.
-L<http://www.iinteractive.com>
+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.
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+=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, 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>.
+
+=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
+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.
+
+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.
=cut
projects / gitmo/Moose.git / blobdiff