Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Moose::Manual::Contributing.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Moose::Manual::Contributing 3"
.TH Moose::Manual::Contributing 3 "2009-10-24" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Moose::Manual::Contributing \- How to get involved in Moose
.SH "GETTING INVOLVED"
.IX Header "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 \*(L"\s-1STANDARD\s0 \s-1WORKFLOW\s0\*(R" 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.
.PP
Note that this document applies to both Moose and Class::MOP development.
.SH "NEW FEATURES"
.IX Header "NEW FEATURES"
Moose already has a fairly large feature set, and we are currently
\&\fBnot\fR 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
MooseX module first.
.PP
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.
.PP
If you think it is 100% impossible, please come discuss it with us on \s-1IRC\s0 or
via e\-mail. 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.
.PP
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 than you might think.
.SH "PEOPLE"
.IX Header "PEOPLE"
As Moose has matured, some structure has emerged in the process.
.IP "Contributors \- people creating a topic or branch" 4
.IX Item "Contributors - people creating a topic or branch"
You.
.Sp
If you have commit access, you can create a topic on the main Moose.git,
otherwise either give us your \s-1SSH\s0 key or create your own clone of the
<git://git.moose.perl.org/Moose.git> repository or fork of the GitHub mirror.
.IP "Core Committers \- people reviewing and merging a branch" 4
.IX Item "Core Committers - people reviewing and merging a branch"
These people have worked with the Moose codebase for a while.
.Sp
They've been responsible for large features or branches and can help review
your changes and apply them to the master branch using the basic
\&\*(L"\s-1APPROVAL\s0 \s-1WORKFLOW\s0\*(R".
.Sp
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
contributors.
.IP "Cabal \- people who can release moose" 4
.IX 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"\s-1CABAL\s0\*(R" in Moose in the Moose documentation. They
merge from Master to Stable.
.SH "BRANCH LAYOUT"
.IX Header "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.
.IP "Stable (refs/heads/stable)" 4
.IX Item "Stable (refs/heads/stable)"
The branch from which releases are cut. When making a new release, the
release manager merges from master to stable. The stable branch is only
updated by someone from the Cabal during a release.
.IP "Master (refs/heads/master)" 4
.IX Item "Master (refs/heads/master)"
The branch for new development. This branch is merged into and branched from.
.IP "Branches (refs/heads/*)" 4
.IX Item "Branches (refs/heads/*)"
Large community branches for big development \*(L"projects\*(R".
.IP "Topics (refs/heads/topic/*)" 4
.IX Item "Topics (refs/heads/topic/*)"
Small personal branches that have been published for review, but can get
freely rebased. Targeted features that may span a handful of commits.
.Sp
Any change or bugfix should be created in a topic branch.
.SH "STANDARD WORKFLOW"
.IX Header "STANDARD WORKFLOW"
.Vb 3
\&    # update your copy of master
\&    git checkout master
\&    git pull \-\-rebase
.Ve
.PP
.Vb 2
\&    # create a new topic branch
\&    git checkout \-b topic/my\-feature
.Ve
.PP
.Vb 4
\&    # hack, commit, feel free to break fast forward
\&    git commit \-\-amend                       # allowed
\&    git rebase \-\-interactive                 # allowed
\&    git push \-\-force origin topic/my_feature # allowed
.Ve
.PP
Then ask for a review/approval (see \*(L"\s-1APPROVAL\s0 \s-1WORKFLOW\s0\*(R"), and merge
to master. If it merges cleanly and nobody has any objections, then it
can be pushed to master.
.PP
If it doesn't merge as a fast forward, the author of the branch needs to run
.PP
.Vb 2
\&    git remote update
\&    git rebase origin/master # or merge
.Ve
.PP
and bring the branch up to date, so that it can be merged as a fast forward
into master.
.PP
No actual merging (as in a human resolving conflicts) should be done when
merging into master, only from master into other branches.
.Sh "Preparing a topic branch"
.IX Subsection "Preparing a topic branch"
Before a merge, a topic branch can be cleaned up by the author.
.PP
This can be done using interactive rebase to combine commits, etc, or even
\&\f(CW\*(C`git merge \-\-squash\*(C'\fR to make the whole topic into a single commit.
.PP
Structuring changes like this makes it easier to apply git revert at a later
date, and encourages a clean and descriptive history that documents what the
author was trying to do, without the various hangups that happened while they
were trying to do it (commits like \*(L"oops forgot that file\*(R" are not only
unnecessary noise, they also make running things like git bisect or git revert
harder).
.PP
However, by far the biggest benefit is that the number of commits that go into
master is eventually reduced, and they are simple and coherent, making it much
easier for people maintaining branches to stay up to date.
.PP
All large changes should be documented in Moose::Manual::Delta.
.SH "APPROVAL WORKFLOW"
.IX Header "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.
.PP
It should be noted that if you want your specific branch to be approved, it is
\&\fByour\fR 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.
.IP "Small bug fixes, doc patches and additional passing tests." 4
.IX 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.
.IP "Larger bug fixes, doc additions and \s-1TODO\s0 or failing tests." 4
.IX 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 \fIcpan-stable-smolder\fR script in the moose-dev-utils
repository.
.Sp
New documentation is always welcome, but should also be reviewed by a cabal
member for accuracy.
.Sp
\&\s-1TODO\s0 tests are basically feature requests, see our \*(L"\s-1NEW\s0 \s-1FEATURES\s0\*(R" section
for more information on that. If your feature needs core support, create a
topic/ branch using the \*(L"\s-1STANDARD\s0 \s-1WORKFLOW\s0\*(R" and start hacking away.
.Sp
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 \s-1RT\s0 queue. Source control is not a bug reporting tool.
.IP "New user-facing features." 4
.IX Item "New user-facing features."
Anything that creates a new user-visible feature needs to be approved by
\&\fBmore than one\fR cabal member.
.Sp
Make sure you have reviewed \*(L"\s-1NEW\s0 \s-1FEATURES\s0\*(R" to be sure that you are following
the guidelines. Do not be surprised if a new feature is rejected for the core.
.IP "New internals features." 4
.IX Item "New internals features."
New features for Moose internals are less restrictive than user facing
features, but still require approval by \fBat least one\fR cabal member.
.Sp
Ideally you will have run the smolder 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.
.IP "Backwards incompatible changes." 4
.IX Item "Backwards incompatible changes."
Anything that breaks backwards compatibility must be discussed by the cabal
and agreed to by a majority of the members.
.Sp
We have a policy for what we see as sane \*(L"\s-1BACKWARDS\s0 \s-1COMPATIBILITY\s0\*(R" for
Moose. If your changes break back\-compat, you must be ready to discuss and
defend your change.
.SH "RELEASE WORKFLOW"
.IX Header "RELEASE WORKFLOW"
.Vb 8
\&    git checkout master
\&    # edit for final version bumping, changelogging, etc
\&    # prepare release (test suite etc)
\&    git commit
\&    git checkout stable
\&    git merge master # must be a fast forward
\&    git push both
\&    # ship & tag
.Ve
.PP
Development releases are made without merging into the stable branch.
.Sh "Release How-To"
.IX Subsection "Release How-To"
Moose (and 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 \s-1API\s0 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.
.PP
For major releases which include an \s-1API\s0 change or deprecation, you should run
the \fIcpan-stable-smolder\fR script from the moose-dev-utils repository. This script tests a
long list of MooseX and other Moose-using modules from \s-1CPAN\s0. 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 install the module, or fiddle with
the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable, whatever makes you happy.
.PP
The smolder script downloads each module from \s-1CPAN\s0, runs its tests, and logs
failures and warnings to a \fIcpan\-stable\-smolder.log\fR file. 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.
.PP
Regardless of whether or not a new module is available, any breakages should
be noted in the conflicts list in the distribution's \fIMakefile.PL\fR.
.PP
Both Class::MOP and Moose have a \fI.shipit\fR 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.
.SH "EMERGENCY BUG WORKFLOW (for immediate release)"
.IX Header "EMERGENCY BUG WORKFLOW (for immediate release)"
Anyone can create the necessary fix by branching off of the stable branch:
.PP
.Vb 4
\&    git remote update
\&    git checkout \-b topic/my\-emergency\-fix origin/stable
\&    # hack
\&    git commit
.Ve
.PP
Then a cabal member merges into stable:
.PP
.Vb 6
\&    git checkout stable
\&    git merge topic/my\-emergency\-fix
\&    git push
\&    # release
\&    git checkout master
\&    git merge stable
.Ve
.SH "PROJECT WORKFLOW"
.IX Header "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 \f(CW\*(C`git pull \-\-rebase\*(C'\fR properly.
.PP
\&\f(CW\*(C`commit \-\-amend\*(C'\fR, \f(CW\*(C`rebase \-\-interactive\*(C'\fR, 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.
.PP
This is pretty much the way we're doing branches for large-ish things right
now.
.PP
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:
.PP
.Vb 1
\&    git checkout \-b my\-project\-\-topic/foo my\-project
.Ve
.PP
(unfortunately Git will not allow \f(CW\*(C`my\-project/foo\*(C'\fR as a branch name if
\&\f(CW\*(C`my\-project\*(C'\fR is a valid ref).
.ie n .SH "THE ""PU"" BRANCH"
.el .SH "THE ``PU'' BRANCH"
.IX Header "THE PU BRANCH"
To make things easier for longer lived branches (whether topics or projects),
the 'pu' branch is basically what happens if you merge all of the branches and
topics together with master.
.PP
We can update this as necessary (e.g. on a weekly basis if there is merit),
notifying the authors of the respective branches if their branches did not merge
(and why).
.PP
To update 'pu':
.PP
.Vb 4
\&    git checkout pu
\&    git remote update
\&    git reset \-\-hard origin/master
\&    git merge @all_the_branches
.Ve
.PP
If the merge is clean, 'pu' is updated with \f(CW\*(C`push \-\-force\*(C'\fR.
.PP
If the merge is not clean, the offending branch is removed from
\&\f(CW@all_the_branches\fR, with a small note of the conflict, and we try again.
.PP
The authors of the failed branches should be told to try to merge their branch
into 'pu', to see how their branch interacts with other branches.
.PP
\&'pu' is probably broken most of the time, but lets us know how the different
branches interact.
.SH "BRANCH ARCHIVAL"
.IX Header "BRANCH ARCHIVAL"
Merged branches should be deleted.
.PP
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.
.PP
Any branch that could still realistically be merged in the future, even if it
hasn't had work recently, should not be archived.
.SH "TESTS, TESTS, TESTS"
.IX Header "TESTS, TESTS, TESTS"
If you write \fIany\fR code for Moose or Class::MOP, you \fBmust\fR 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.
.PP
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.
.PP
We also greatly appreciate documentation to go with your changes, and
an entry in the Changes file. Make sure to give yourself credit!
.SH "BACKWARDS COMPATIBILITY"
.IX Header "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.
.PP
The rule is that if you do something that is not backwards compatible, you
\&\fBmust\fR do \fIat least\fR one deprecation cycle (more if it is larger change).
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).
.PP
The preference with regard to deprecation is to warn loudly and often so that
users will have time to fix their usages.
.PP
All backwards incompatible changes \fBmust\fR be documented in
Moose::Manual::Delta. Make sure to document any useful tips or workarounds
for the change in that document.
.SH "AUTHOR"
.IX Header "AUTHOR"
Stevan Little <stevan@iinteractive.com>
.PP
Chris (perigrin) Prather
.PP
Yuval (nothingmuch) Kogman
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2009 by Infinity Interactive, Inc.
.PP
<http://www.iinteractive.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.