Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

Moose::Manual::Contributing(3)       User Contributed Perl Documentation      Moose::Manual::Contributing(3)



NAME
       Moose::Manual::Contributing - How to get involved in Moose

VERSION
       version 2.0205

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
       Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE
       This software is copyright (c) 2011 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.12.5                                     2011-09-06                   Moose::Manual::Contributing(3)