Moose::Manual::ContribUsergContributed Perl DocuMoose::Manual::Contributing(3)NAME
Moose::Manual::Contributing - How to get involved in Moose
VERSION
version 2.0604
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 the "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.
NEW FEATURES
Moose already has a fairly large feature set, and we are currently 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.
PEOPLE
As Moose has matured, some structure has emerged in the process.
Contributors - people creating a topic or branch
You.
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
<git://git.moose.perl.org/Moose.git> repository.
The relevant repository URIs are:
Read-Only
<git://git.moose.perl.org/Moose.git>
Read+Write
gitmo@git.moose.perl.org:Moose.git
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 "CABAL" in Moose 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 Moose and can often be found on irc in
the irc://irc.perl.org/#moose-dev <irc://irc.perl.org/#moose-dev>
channel.
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.
stable/*
The branch from which releases are cut. When making a new major
release, the release manager makes a new "stable/X.YY" branch at
the current position of "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 "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.
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
"stable" to be included in the next minor release.
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 "master" if they are acceptable, or move them back to a
different namespace otherwise.
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.
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.
abandoned/*
Topic branches which have had no activity for a long period of time
will be moved here, to keep the main areas clean.
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.
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
"rfc/" namespace and is rebased on top of master, and ask for
review/approval (see "APPROVAL WORKFLOW"). If it is approved, the
reviewer will merge it into "master".
No actual merging (as in a human resolving conflicts) should be done
when merging into "master", only from "master" into other branches.
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 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.
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.
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 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 "NEW FEATURES"
section for more information on that. If your feature needs core
support, create a "topic/" branch using the "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.
New user-facing features.
Anything that creates a new user-visible feature needs to be
approved by more than one cabal member.
Make sure you have reviewed "NEW FEATURES" to be sure that you are
following the guidelines. Do not be surprised if a new feature is
rejected for the core.
New internals features.
New features for Moose internals are less restrictive than user
facing features, but still require approval by at least one cabal
member.
Ideally you will have run the 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.
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 "BACKWARDS COMPATIBILITY"
for Moose. If your changes break back-compat, you must be ready to
discuss and defend your change.
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
Release How-To
Moose uses Dist::Zilla to manage releases. Although the git repository
comes with a "Makefile.PL", it is a very basic one just to allow the
basic "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: "cpanm Dist::Zilla", and then install the plugins necessary for
reading the "dist.ini": "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 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 "prove -b" and "prove -I", install the
module, or fiddle with the "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 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 dist.ini.
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 "master", and backports the change into
"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
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 "git pull --rebase"
properly.
"commit --amend", "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 "my-project/foo" as a branch name if
"my-project" is a valid ref).
BRANCH ARCHIVAL
Merged branches should be deleted.
Failed branches may be kept, but should be moved to "attic/" to
differentiate them from in-progress topic branches.
Branches that have not been worked on for a long time will be moved to
"abandoned/" periodically, but feel free to move the branch back to
"topic/" if you want to start working on it again.
TESTS, TESTS, TESTS
If you write any code for Moose, you 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
Moose::Manual::Delta.
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.
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 Moose::Manual::Support.
All backwards incompatible changes must be documented in
Moose::Manual::Delta. Make sure to document any useful tips or
workarounds for the change in that document.
AUTHOR
Moose is maintained by the Moose Cabal, along with the help of many
contributors. See "CABAL" in Moose and "CONTRIBUTORS" in Moose for
details.
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 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.
perl v5.16.2 2012-09-19 Moose::Manual::Contributing(3)
