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
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 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 PEOPLE
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> repo or fork of the GitHub mirror.
+If you have commit access, you can create a topic on the main Moose.git
+repository. If you don't have a commit bit, give us your SSH key or create your
+own clone of the L<git://git.moose.perl.org/Moose.git> repository.
+
+The relevant repository URIs are:
+
+=over
+
+=item Read-Only
+
+L<git://git.moose.perl.org/Moose.git>
+
+=item Read+Write
+
+L<gitmo@git.moose.perl.org:Moose.git>
+
+=back
=item Core Committers - people reviewing and merging a branch
These people have worked with the Moose codebase for a while.
They've been responsible for large features or branches and can help review
-your changes and apply them to the master branch.
+your changes and apply them to the master branch using the basic
+L</APPROVAL WORKFLOW>.
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
=head1 BRANCH LAYOUT
-The repository is divided into several branches to make maintaince easier for
+The repository is divided into several branches to make maintenance easier for
everyone involved. The branches below are ordered by level of stability.
=over
Large community branches for big development "projects".
-=item Topics (refs/heads/topics/*)
+=item Topics (refs/heads/topic/*)
Small personal branches that have been published for review, but can get
-freely rebased. Targetted features that may span a handful of commits.
+freely rebased. Targeted features that may span a handful of commits.
Any change or bugfix should be created in a topic branch.
git pull --rebase
# create a new topic branch
- git checkout -b topic/my-feature
+ git checkout -b topic/my-feature origin/master
# 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 go on IRC, ask for someone to review, and merge to master. If it merges
-cleanly and nobody has any objections, then it can be pushed to master.
+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
All large changes should be documented in L<Moose::Manual::Delta>.
+=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.
+
+=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
+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
+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
+defend your change.
+
+=back
+
=head1 RELEASE WORKFLOW
git checkout master
# edit for final version bumping, changelogging, etc
# prepare release (test suite etc)
+ perl-reversion -bump
+ make manifest
git commit
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<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.
+
+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<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:
git remote update
- git checkout -b topic/my-emergency-fix origin/master
+ git checkout -b topic/my-emergency-fix origin/stable
# hack
git commit
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 contributers are using C<git pull --rebase> properly.
+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 largeish things right
+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
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.
-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
+refs/abandoned/ periodically, but feel free to move the branch back to
+refs/topic/ if you want to start working on it again.
=head1 TESTS, TESTS, TESTS
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 with deprecation is that each deprecation should go through several
+stages. First, we simply add a deprecation notice the documentation in
+F<Changes> and L<Moose::Manual::Delta>. In a future release, we then make the
+deprecated feature warn loudly and often so that users will have time to fix
+their usages. Finally, the feature is removed in a later release.
All backwards incompatible changes B<must> be documented in
L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
=head1 COPYRIGHT AND LICENSE
-Copyright 2009 by Infinity Interactive, Inc.
+Copyright 2009-2010 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
projects / gitmo/Moose.git / blobdiff