# PODNAME: Moose::Manual::Contributing
# ABSTRACT: How to get involved in Moose
__END__
=pod
=encoding UTF-8
=head1 NAME
Moose::Manual::Contributing - How to get involved in Moose
=head1 VERSION
version 2.1210
=head1 GETTING INVOLVED
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
it's easy to get started!
=head2 Get the Code
If you just want to get your feet wet and check out the code, you can do so
from the comfort of your web browser by going to the official repository on
GitHub: L<https://github.com/moose/Moose>.
However, if you know how to use git and would rather have a local copy
(because, why wouldn't you?!), then you can clone it:
git clone git@github.com:moose/Moose.git
If, at some point, you think you'd like to contribute a patch, please see
L</Getting Started>.
I<B<NOTE:> Your contribution is very important to us. If, for some reason,
you would prefer not to use Git/GitHub, come talk to us at #moose on
irc.perl.org and we can work something out.>
=head2 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!
=back
=head2 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 encouraged to create a
MooseX module first.
At this stage, no new features will even be considered for addition
into the core without first being vetted as a MooseX module, unless
it is absolutely 100% impossible to implement the feature outside the
core.
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.
=head2 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 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 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.
This namespace is being phased out now that we are using GitHub's pull
requests in our L</Development Workflow>.
=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 WORKFLOWS
=head2 Getting Started
So, you've cloned the main Moose repository to your local machine (see
L</Get the Code>) and you're ready to do some hacking. We couldn't be
happier to welcome you to our community!
Of course, to ensure that your first experience is as productive and
satisfying as possible, you should probably take some time to read over this
entire POD document. Doing so will give you a full understanding of how Moose
developers and maintainers work together and what they expect from one
another. Done? Great!
Next, assuming you have a GitHub account, go to
L<http://github.com/moose/Moose> and B<fork the repository> (see
L<https://help.github.com/articles/fork-a-repo>). This will put an exact
replica of the Moose repository into your GitHub account, which will serve as
a place to publish your patches for the Moose maintainers to review and
incorporate.
Once your fork has been created, switch to your local working repository directory
and update your C<origin> remote's push URL. This allows you to use a single
remote (C<origin>) to both pull in the latest code from GitHub and also push
your work to your own fork:
# Replace YOUR_USERNAME below with your GitHub username
git remote set-url --push origin git@github.com:YOUR_USERNAME/moose.git
You can verify your work:
$ git remote -v
origin git@github.com:moose/Moose.git (fetch)
origin git@github.com:YOUR_USERNAME/moose.git (push)
Now, you're ready for action! From now on, you just follow the L</Development
Workflow> to publish your work and B<submit pull requests> to the Moose Cabal.
=head2 Development Workflow
The general gist of the B<STANDARD WORKFLOW> is:
=over 4
=item 1. Update your local repository with the latest commits from the official repository
=item 2. Create a new topic branch, based on the master branch
=item 3. Hack away
=item 4. Commit and push the topic branch to your forked repository
=item 5. Submit a pull request through GitHub for that branch
=back
What follows is a more detailed rundown of that workflow. Please make sure to
review and follow the steps in the previous section, L</Getting Started>, if
you have not done so already.
=head3 Update Your Repository
Update your local copy of the master branch from the remote:
git checkout master
git pull --rebase
=head3 Create Your Topic Branch
Now, create a new topic branch based on your master branch. It's useful to
use concise, descriptive branch names such as: pod-syntax-contrib,
feat-autodelegation, patch-23-role-comp, etc. However, we'll just call ours
C<my-feature> for demonstration purposes:
git checkout -b topic/my-feature
=head3 Hack. Commit. Repeat.
While you're hacking, the most important thing to remember is that your topic
branch is yours to do with as you like. Nothing you do there will affect
anyone else at this point. Commit as often as little or as often as you need
to and don't let perfection get in the way of progress. However, don't try to
do too much as the easiest changes to integrate are small and focused.
If it's been a while since you created your topic branch, it's often a good
idea to periodically rebase your branch off of the upstream master to reduce
your work later on:
git fetch # or, git remote update
git rebase origin/master # or, git pull --rebase origin master
You should also feel free to publish (using C<push --force> if necessary) your
branch to your GitHub fork if you simply need feedback from others. (Note:
actual collaboration takes a bit more finesse and a lot less C<--force>
however).
=head3 Clean Up Your Branch
Finally, when your development is done, it's time to prepare your branch for
review. Even the smallest branches can often use a little bit of tidying up
before they are unleashed on a reviewer. Clarifying/cleaning up commit
messages, reordering commits, splitting large commits or those which contain
different types of changes, squashing related or straggler commits are all
B<highly> worthwhile activities to undertake on your topic branch.
B<Remember:> Your topic branch is yours. Don't worry about rewriting its
history or breaking fast-forward. Some useful commands are listed below but
please make sure that you understand what they do as they can rewrite history:
- git commit --amend
- git rebase --interactive
- git cherry-pick
Ultimately, your goal in cleaning up your branch is to craft a set of commits
whose content and messages are as focused and understandable as possible.
Doing so will greatly increase the chances of a speedy review and acceptance
into the mainline development.
=head3 Rebase on the Latest
Before your final push and issuing a pull request, you need to ensure that
your changes can be easily merged into the master branch of the upstream
repository. This is done by once again rebasing your branch on the latest
C<origin/master>.
git fetch # or, git remote update
git rebase origin/master # or, git pull --rebase origin master
=head3 Publish and Pull Request
Now it's time to make your final push of the branch to your fork. The
C<--force> flag is only necessary if you've pushed before and subsequently
rewriting your history:
git push --force
After your branch is published, you can issue a pull request to the Moose
Cabal. See <https://help.github.com/articles/using-pull-requests> for details.
Congratulations! You're now a contributor!
=head2 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.
=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.
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</Development 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
=head2 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
=head3 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 Perls. Testing should be done against
at least two recent major versions 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>.
=head2 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
=head2 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.
=head1 AUTHORS
=over 4
=item *
Stevan Little <stevan.little@iinteractive.com>
=item *
Dave Rolsky <autarch@urth.org>
=item *
Jesse Luehrs <doy@tozt.net>
=item *
Shawn M Moore <code@sartak.org>
=item *
יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
=item *
Karen Etheridge <ether@cpan.org>
=item *
Florian Ragwitz <rafl@debian.org>
=item *
Hans Dieter Pearcey <hdp@weftsoar.net>
=item *
Chris Prather <chris@prather.org>
=item *
Matt S Trout <mst@shadowcat.co.uk>
=back
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2006 by Infinity Interactive, Inc..
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut