1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Moose::Manual::Contributing 3"
132 .TH Moose::Manual::Contributing 3 "2009-10-24" "perl v5.8.7" "User Contributed Perl Documentation"
134 Moose::Manual::Contributing \- How to get involved in Moose
135 .SH "GETTING INVOLVED"
136 .IX Header "GETTING INVOLVED"
137 Moose is an open project, and we are always willing to accept bug fixes,
138 more tests, and documentation patches. Commit bits are given out freely, and
139 the \*(L"\s-1STANDARD\s0 \s-1WORKFLOW\s0\*(R" is very simple. The general gist is: clone the Git
140 repository, create a new topic branch, hack away, then find a committer to
143 Note that this document applies to both Moose and Class::MOP development.
145 .IX Header "NEW FEATURES"
146 Moose already has a fairly large feature set, and we are currently
147 \&\fBnot\fR looking to add any major new features to it. If you have an
148 idea for a new feature in Moose, you are invited instead to create a
151 At this stage, no new features will even be considered for addition
152 into the core without first being vetted as a MooseX module, unless
153 it is absolutely 100% impossible to implement the feature outside the
156 If you think it is 100% impossible, please come discuss it with us on \s-1IRC\s0 or
157 via e\-mail. However, your feature may need a small hook in the core, or a
158 refactoring of some core modules, and we are definitely open to that.
160 Moose was built from the ground up with the idea of being highly
161 extensible, and quite often the feature requests we see can be
162 implemented through a couple of small and well placed extensions. Try
163 it, it is much easier than you might think.
166 As Moose has matured, some structure has emerged in the process.
167 .IP "Contributors \- people creating a topic or branch" 4
168 .IX Item "Contributors - people creating a topic or branch"
171 If you have commit access, you can create a topic on the main Moose.git,
172 otherwise either give us your \s-1SSH\s0 key or create your own clone of the
173 <git://git.moose.perl.org/Moose.git> repository or fork of the GitHub mirror.
174 .IP "Core Committers \- people reviewing and merging a branch" 4
175 .IX Item "Core Committers - people reviewing and merging a branch"
176 These people have worked with the Moose codebase for a while.
178 They've been responsible for large features or branches and can help review
179 your changes and apply them to the master branch using the basic
180 \&\*(L"\s-1APPROVAL\s0 \s-1WORKFLOW\s0\*(R".
182 They are also fairly well versed in Git, in order to merge the branches with
183 no mistakes (especially when the merge fails), and to provide advice to
185 .IP "Cabal \- people who can release moose" 4
186 .IX Item "Cabal - people who can release moose"
187 These people are the ones who have co-maint on Moose itself and can create a
188 release. They're listed under \*(L"\s-1CABAL\s0\*(R" in Moose in the Moose documentation. They
189 merge from Master to Stable.
191 .IX Header "BRANCH LAYOUT"
192 The repository is divided into several branches to make maintenance easier for
193 everyone involved. The branches below are ordered by level of stability.
194 .IP "Stable (refs/heads/stable)" 4
195 .IX Item "Stable (refs/heads/stable)"
196 The branch from which releases are cut. When making a new release, the
197 release manager merges from master to stable. The stable branch is only
198 updated by someone from the Cabal during a release.
199 .IP "Master (refs/heads/master)" 4
200 .IX Item "Master (refs/heads/master)"
201 The branch for new development. This branch is merged into and branched from.
202 .IP "Branches (refs/heads/*)" 4
203 .IX Item "Branches (refs/heads/*)"
204 Large community branches for big development \*(L"projects\*(R".
205 .IP "Topics (refs/heads/topic/*)" 4
206 .IX Item "Topics (refs/heads/topic/*)"
207 Small personal branches that have been published for review, but can get
208 freely rebased. Targeted features that may span a handful of commits.
210 Any change or bugfix should be created in a topic branch.
211 .SH "STANDARD WORKFLOW"
212 .IX Header "STANDARD WORKFLOW"
214 \& # update your copy of master
215 \& git checkout master
216 \& git pull \-\-rebase
220 \& # create a new topic branch
221 \& git checkout \-b topic/my\-feature
225 \& # hack, commit, feel free to break fast forward
226 \& git commit \-\-amend # allowed
227 \& git rebase \-\-interactive # allowed
228 \& git push \-\-force origin topic/my_feature # allowed
231 Then ask for a review/approval (see \*(L"\s-1APPROVAL\s0 \s-1WORKFLOW\s0\*(R"), and merge
232 to master. If it merges cleanly and nobody has any objections, then it
233 can be pushed to master.
235 If it doesn't merge as a fast forward, the author of the branch needs to run
239 \& git rebase origin/master # or merge
242 and bring the branch up to date, so that it can be merged as a fast forward
245 No actual merging (as in a human resolving conflicts) should be done when
246 merging into master, only from master into other branches.
247 .Sh "Preparing a topic branch"
248 .IX Subsection "Preparing a topic branch"
249 Before a merge, a topic branch can be cleaned up by the author.
251 This can be done using interactive rebase to combine commits, etc, or even
252 \&\f(CW\*(C`git merge \-\-squash\*(C'\fR to make the whole topic into a single commit.
254 Structuring changes like this makes it easier to apply git revert at a later
255 date, and encourages a clean and descriptive history that documents what the
256 author was trying to do, without the various hangups that happened while they
257 were trying to do it (commits like \*(L"oops forgot that file\*(R" are not only
258 unnecessary noise, they also make running things like git bisect or git revert
261 However, by far the biggest benefit is that the number of commits that go into
262 master is eventually reduced, and they are simple and coherent, making it much
263 easier for people maintaining branches to stay up to date.
265 All large changes should be documented in Moose::Manual::Delta.
266 .SH "APPROVAL WORKFLOW"
267 .IX Header "APPROVAL WORKFLOW"
268 Moose is an open project but it is also an increasingly important one. Many
269 modules depend on Moose being stable. Therefore, we have a basic set of
270 criteria for reviewing and merging branches. What follows is a set of rough
271 guidelines that ensures all new code is properly vetted before it is merged to
274 It should be noted that if you want your specific branch to be approved, it is
275 \&\fByour\fR responsibility to follow this process and advocate for your branch.
276 The preferred way is to send a request to the mailing list for review/approval,
277 this allows us to better keep track of the branches awaiting approval and those
278 which have been approved.
279 .IP "Small bug fixes, doc patches and additional passing tests." 4
280 .IX Item "Small bug fixes, doc patches and additional passing tests."
281 These items don't really require approval beyond one of the core contributors
282 just doing a simple review.
283 .IP "Larger bug fixes, doc additions and \s-1TODO\s0 or failing tests." 4
284 .IX Item "Larger bug fixes, doc additions and TODO or failing tests."
285 Larger bug fixes should be reviewed by at least one cabal member and should be
286 tested using the \fIcpan-stable-smolder\fR script in the moose-dev-utils
289 New documentation is always welcome, but should also be reviewed by a cabal
292 \&\s-1TODO\s0 tests are basically feature requests, see our \*(L"\s-1NEW\s0 \s-1FEATURES\s0\*(R" section
293 for more information on that. If your feature needs core support, create a
294 topic/ branch using the \*(L"\s-1STANDARD\s0 \s-1WORKFLOW\s0\*(R" and start hacking away.
296 Failing tests are basically bug reports. You should find a core contributor
297 and/or cabal member to see if it is a real bug, then submit the bug and your
298 test to the \s-1RT\s0 queue. Source control is not a bug reporting tool.
299 .IP "New user-facing features." 4
300 .IX Item "New user-facing features."
301 Anything that creates a new user-visible feature needs to be approved by
302 \&\fBmore than one\fR cabal member.
304 Make sure you have reviewed \*(L"\s-1NEW\s0 \s-1FEATURES\s0\*(R" to be sure that you are following
305 the guidelines. Do not be surprised if a new feature is rejected for the core.
306 .IP "New internals features." 4
307 .IX Item "New internals features."
308 New features for Moose internals are less restrictive than user facing
309 features, but still require approval by \fBat least one\fR cabal member.
311 Ideally you will have run the smolder script to be sure you are not breaking
312 any MooseX module or causing any other unforeseen havoc. If you do this
313 (rather than make us do it), it will only help to hasten your branch's
315 .IP "Backwards incompatible changes." 4
316 .IX Item "Backwards incompatible changes."
317 Anything that breaks backwards compatibility must be discussed by the cabal
318 and agreed to by a majority of the members.
320 We have a policy for what we see as sane \*(L"\s-1BACKWARDS\s0 \s-1COMPATIBILITY\s0\*(R" for
321 Moose. If your changes break back\-compat, you must be ready to discuss and
323 .SH "RELEASE WORKFLOW"
324 .IX Header "RELEASE WORKFLOW"
326 \& git checkout master
327 \& # edit for final version bumping, changelogging, etc
328 \& # prepare release (test suite etc)
330 \& git checkout stable
331 \& git merge master # must be a fast forward
336 Development releases are made without merging into the stable branch.
338 .IX Subsection "Release How-To"
339 Moose (and Class::MOP) releases fall into two categories, each with their
340 own level of release preparation. A minor release is one which does not
341 include any \s-1API\s0 changes, deprecations, and so on. In that case, it is
342 sufficient to simply test the release candidate against a few different
343 different Perls. Testing should be done against at least two recent major
344 version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
345 available, you are encouraged to test them all. However, we do not put a lot
346 of effort into supporting older 5.8.x releases.
348 For major releases which include an \s-1API\s0 change or deprecation, you should run
349 the \fIcpan-stable-smolder\fR script from the moose-dev-utils repository. This script tests a
350 long list of MooseX and other Moose-using modules from \s-1CPAN\s0. In order to run
351 this script, you must arrange to have the new version of Moose and/or
352 Class::MOP in Perl's include path. You can install the module, or fiddle with
353 the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable, whatever makes you happy.
355 The smolder script downloads each module from \s-1CPAN\s0, runs its tests, and logs
356 failures and warnings to a \fIcpan\-stable\-smolder.log\fR file. If there are
357 failures or warnings, please work with the authors of the modules in question
358 to fix them. If the module author simply isn't available or does not want to
359 fix the bug, it is okay to make a release.
361 Regardless of whether or not a new module is available, any breakages should
362 be noted in the conflicts list in the distribution's \fIMakefile.PL\fR.
364 Both Class::MOP and Moose have a \fI.shipit\fR file you can use to make sure the
365 release goes smoothly. You are strongly encouraged to use this instead of
366 doing the final release steps by hand.
367 .SH "EMERGENCY BUG WORKFLOW (for immediate release)"
368 .IX Header "EMERGENCY BUG WORKFLOW (for immediate release)"
369 Anyone can create the necessary fix by branching off of the stable branch:
373 \& git checkout \-b topic/my\-emergency\-fix origin/stable
378 Then a cabal member merges into stable:
381 \& git checkout stable
382 \& git merge topic/my\-emergency\-fix
385 \& git checkout master
388 .SH "PROJECT WORKFLOW"
389 .IX Header "PROJECT WORKFLOW"
390 For longer lasting branches, we use a subversion style branch layout, where
391 master is routinely merged into the branch. Rebasing is allowed as long as all
392 the branch contributors are using \f(CW\*(C`git pull \-\-rebase\*(C'\fR properly.
394 \&\f(CW\*(C`commit \-\-amend\*(C'\fR, \f(CW\*(C`rebase \-\-interactive\*(C'\fR, etc. are not allowed, and should
395 only be done in topic branches. Committing to master is still done with the
396 same review process as a topic branch, and the branch must merge as a fast
399 This is pretty much the way we're doing branches for large-ish things right
402 Obviously there is no technical limitation on the number of branches. You can
403 freely create topic branches off of project branches, or sub projects inside
404 larger projects freely. Such branches should incorporate the name of the branch
405 they were made off so that people don't accidentally assume they should be
409 \& git checkout \-b my\-project\-\-topic/foo my\-project
412 (unfortunately Git will not allow \f(CW\*(C`my\-project/foo\*(C'\fR as a branch name if
413 \&\f(CW\*(C`my\-project\*(C'\fR is a valid ref).
414 .ie n .SH "THE ""PU"" BRANCH"
415 .el .SH "THE ``PU'' BRANCH"
416 .IX Header "THE PU BRANCH"
417 To make things easier for longer lived branches (whether topics or projects),
418 the 'pu' branch is basically what happens if you merge all of the branches and
419 topics together with master.
421 We can update this as necessary (e.g. on a weekly basis if there is merit),
422 notifying the authors of the respective branches if their branches did not merge
430 \& git reset \-\-hard origin/master
431 \& git merge @all_the_branches
434 If the merge is clean, 'pu' is updated with \f(CW\*(C`push \-\-force\*(C'\fR.
436 If the merge is not clean, the offending branch is removed from
437 \&\f(CW@all_the_branches\fR, with a small note of the conflict, and we try again.
439 The authors of the failed branches should be told to try to merge their branch
440 into 'pu', to see how their branch interacts with other branches.
442 \&'pu' is probably broken most of the time, but lets us know how the different
444 .SH "BRANCH ARCHIVAL"
445 .IX Header "BRANCH ARCHIVAL"
446 Merged branches should be deleted.
448 Failed branches may be kept, but consider moving to refs/attic/ (e.g.
449 http://danns.co.uk/node/295) to keep git branch \-l current.
451 Any branch that could still realistically be merged in the future, even if it
452 hasn't had work recently, should not be archived.
453 .SH "TESTS, TESTS, TESTS"
454 .IX Header "TESTS, TESTS, TESTS"
455 If you write \fIany\fR code for Moose or Class::MOP, you \fBmust\fR add
456 tests for that code. If you do not write tests then we cannot
457 guarantee your change will not be removed or altered at a later date,
458 as there is nothing to confirm this is desired behavior.
460 If your code change/addition is deep within the bowels of
461 Moose/Class::MOP and your test exercises this feature in a non-obvious
462 way, please add some comments either near the code in question or in
463 the test so that others know.
465 We also greatly appreciate documentation to go with your changes, and
466 an entry in the Changes file. Make sure to give yourself credit!
467 .SH "BACKWARDS COMPATIBILITY"
468 .IX Header "BACKWARDS COMPATIBILITY"
469 Change is inevitable, and Moose is not immune to this. We do our best
470 to maintain backwards compatibility, but we do not want the code base
471 to become overburdened by this. This is not to say that we will be
472 frivolous with our changes, quite the opposite, just that we are not
473 afraid of change and will do our best to keep it as painless as
474 possible for the end user.
476 The rule is that if you do something that is not backwards compatible, you
477 \&\fBmust\fR do \fIat least\fR one deprecation cycle (more if it is larger change).
478 For really larger or radical changes dev releases may be needed as well (the
479 Cabal will decide on this on a case-per-case basis).
481 The preference with regard to deprecation is to warn loudly and often so that
482 users will have time to fix their usages.
484 All backwards incompatible changes \fBmust\fR be documented in
485 Moose::Manual::Delta. Make sure to document any useful tips or workarounds
486 for the change in that document.
489 Stevan Little <stevan@iinteractive.com>
491 Chris (perigrin) Prather
493 Yuval (nothingmuch) Kogman
494 .SH "COPYRIGHT AND LICENSE"
495 .IX Header "COPYRIGHT AND LICENSE"
496 Copyright 2009 by Infinity Interactive, Inc.
498 <http://www.iinteractive.com>
500 This library is free software; you can redistribute it and/or modify
501 it under the same terms as Perl itself.
projects / catagits/Gitalist.git / blob