5 Moose::Manual::Contributing - How to get involved in Moose
7 =head1 GETTING INVOLVED
9 Moose is an open project, and we are always willing to accept bug fixes,
10 more tests, and documentation patches. Commit bits are given out freely, and
11 the L</STANDARD WORKFLOW> is very simple. The general gist is: clone the Git
12 repository, create a new topic branch, hack away, then find a committer to
15 Note that this document applies to both Moose and L<Class::MOP> development.
19 Moose already has a fairly large feature set, and we are currently
20 B<not> looking to add any major new features to it. If you have an
21 idea for a new feature in Moose, you are encouraged to create a
24 At this stage, no new features will even be considered for addition
25 into the core without first being vetted as a MooseX module, unless
26 it is absolutely 100% impossible to implement the feature outside the
29 If you think it is 100% impossible, please come discuss it with us on IRC or
30 via e-mail. Your feature may need a small hook in the core, or a
31 refactoring of some core modules, and we are definitely open to that.
33 Moose was built from the ground up with the idea of being highly extensible,
34 and quite often the feature requests we see can be implemented through small
35 extensions. Try it, it's much easier than you might think.
39 As Moose has matured, some structure has emerged in the process.
43 =item Contributors - people creating a topic or branch
47 If you have commit access, you can create a topic on the main Moose.git
48 repository. If you don't have a commit bit, give us your SSH key or create your
49 own clone of the L<git://git.moose.perl.org/Moose.git> repository.
51 The relevant repository URIs are:
57 L<git://git.moose.perl.org/Moose.git>
61 L<gitmo@git.moose.perl.org:Moose.git>
65 =item Cabal - people who can release moose
67 These people are the ones who have co-maint on Moose itself and can create a
68 release. They're listed under L<Moose/CABAL> in the Moose documentation. They
69 are responsible for reviewing branches, and are the only people who are allowed
70 to push to stable branches.
72 Cabal members are listed in L<Moose> and can often be found on irc in the
73 L<irc://irc.perl.org/#moose-dev> channel.
79 The repository is divided into several branches to make maintenance easier for
80 everyone involved. The branches below are ordered by level of stability.
86 The branch from which releases are cut. When making a new major release, the
87 release manager makes a new C<stable/$version> branch at the current position
88 of C<master>. For minor releases, patches will be committed to C<master>, and
89 backported (cherry-picked) to the appropriate stable branch as needed. The
90 C<stable> branch is only updated by someone from the Cabal during a release.
94 The main development branch. All new code should be written against this
95 branch. This branch contains code that has been reviewed, and will be included
96 in the next major release. Commits which are judged to not break backwards
97 compatibility may be backported into C<stable> to be included in the next minor
102 Topic branches that are completed and waiting on review. A Cabal member will
103 look over branches in this namespace, and either merge them to C<master> if
104 they are acceptable, or move them back to a different namespace otherwise.
108 Small personal branches that are still in progress. They can be freely rebased.
109 They contain targeted features that may span a handful of commits. Any change
110 or bugfix should be created in a topic branch.
114 Branches which have been reviewed, and rejected. They remain in the repository
115 in case we later change our mind, or in case parts of them are still useful.
119 Topic branches which have had no activity for a long period of time will be
120 moved here, to keep the main areas clean.
124 Larger, longer term branches can also be created in the root namespace (i.e.
125 at the same level as master and stable). This may be appropriate if multiple
126 people are intending to work on the branch. These branches should not be
127 rebased without checking with other developers first.
129 =head1 STANDARD WORKFLOW
131 # update your copy of master
135 # create a new topic branch
136 git checkout -b topic/my-feature
138 # hack, commit, feel free to break fast forward
139 git commit --amend # allowed
140 git rebase --interactive # allowed
141 git push --force # allowed
143 # keep the branch rebased on top of master, for easy reviewing
145 git rebase origin/master
148 # when finished, move the branch to the rfc/ namespace
149 git branch -m rfc/my-feature
151 git push origin :topic/my-feature
153 When your branch is completed, make sure it has been moved to the C<rfc/>
154 namespace and is rebased on top of master, and ask for review/approval (see
155 L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
158 No actual merging (as in a human resolving conflicts) should be done when
159 merging into C<master>, only from C<master> into other branches.
161 =head1 APPROVAL WORKFLOW
163 Moose is an open project but it is also an increasingly important one. Many
164 modules depend on Moose being stable. Therefore, we have a basic set of
165 criteria for reviewing and merging branches. What follows is a set of rough
166 guidelines that ensures all new code is properly vetted before it is merged to
169 It should be noted that if you want your specific branch to be approved, it is
170 B<your> responsibility to follow this process and advocate for your branch. The
171 preferred way is to send a request to the mailing list for review/approval;
172 this allows us to better keep track of the branches awaiting approval and those
173 which have been approved.
177 =item Small bug fixes, doc patches and additional passing tests.
179 These items don't really require approval beyond one of the core contributors
180 just doing a simple review. For especially simple patches (doc patches
181 especially), committing directly to master is fine.
183 =item Larger bug fixes, doc additions and TODO or failing tests.
185 Larger bug fixes should be reviewed by at least one cabal member and should be
186 tested using the F<xt/author/test-my-dependents.t> test.
188 New documentation is always welcome, but should also be reviewed by a cabal
191 TODO tests are basically feature requests, see our L</NEW FEATURES> section
192 for more information on that. If your feature needs core support, create a
193 C<topic/> branch using the L</STANDARD WORKFLOW> and start hacking away.
195 Failing tests are basically bug reports. You should find a core contributor
196 and/or cabal member to see if it is a real bug, then submit the bug and your
197 test to the RT queue. Source control is not a bug reporting tool.
199 =item New user-facing features.
201 Anything that creates a new user-visible feature needs to be approved by
202 B<more than one> cabal member.
204 Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
205 the guidelines. Do not be surprised if a new feature is rejected for the core.
207 =item New internals features.
209 New features for Moose internals are less restrictive than user facing
210 features, but still require approval by B<at least one> cabal member.
212 Ideally you will have run the F<test-my-dependents.t> script to be sure you
213 are not breaking any MooseX module or causing any other unforeseen havoc. If
214 you do this (rather than make us do it), it will only help to hasten your
217 =item Backwards incompatible changes.
219 Anything that breaks backwards compatibility must be discussed by the
220 cabal. Backwards incompatbible changes should not be merged to master if there
221 are strong objections for any cabal members.
223 We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
224 Moose. If your changes break back-compat, you must be ready to discuss and
229 =head1 RELEASE WORKFLOW
231 # major releases (including trial releases)
237 # edit for final version bumping, changelogging, etc
238 # prepare release (test suite etc)
242 git branch stable/2.XXYY # only for non-trial major releases
243 shipit # does not ship the tarball, but does everything else
246 cpan-upload ~/shipit-dist/Moose-2.XXYY.tar.gz
250 mv Moose-2.XXYY.tar.gz Moose-2.XXYY-TRIAL.tar.gz
251 cpan-upload Moose-2.XXYY-TRIAL.tar.gz
253 =head2 Release How-To
255 Moose (and L<Class::MOP>) releases fall into two categories, each with their
256 own level of release preparation. A minor release is one which does not
257 include any API changes, deprecations, and so on. In that case, it is
258 sufficient to simply test the release candidate against a few different
259 different Perls. Testing should be done against at least two recent major
260 version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
261 available, you are encouraged to test them all. However, we do not put a lot
262 of effort into supporting older 5.8.x releases.
264 For major releases which include an API change or deprecation, you should run
265 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
266 and other Moose-using modules from CPAN. In order to run this script, you must
267 arrange to have the new version of Moose and/or Class::MOP in Perl's include
268 path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle
269 with the C<PERL5LIB> environment variable, whatever makes you happy.
271 This test downloads each module from CPAN, runs its tests, and logs failures
272 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
273 failures or warnings, please work with the authors of the modules in question
274 to fix them. If the module author simply isn't available or does not want to
275 fix the bug, it is okay to make a release.
277 Regardless of whether or not a new module is available, any breakages should
278 be noted in the conflicts list in the distribution's F<Makefile.PL>.
280 Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the
281 release goes smoothly. You are strongly encouraged to use this instead of
282 doing the final release steps by hand.
284 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
286 The stable branch exists for easily making bug fix releases.
289 git checkout -b topic/my-emergency-fix origin/master
293 Then a cabal member merges into C<master>, and backports the change into
297 git merge topic/my-emergency-fix
300 git cherry-pick -x master
304 =head1 PROJECT WORKFLOW
306 For longer lasting branches, we use a subversion style branch layout, where
307 master is routinely merged into the branch. Rebasing is allowed as long as all
308 the branch contributors are using C<git pull --rebase> properly.
310 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
311 only be done in topic branches. Committing to master is still done with the
312 same review process as a topic branch, and the branch must merge as a fast
315 This is pretty much the way we're doing branches for large-ish things right
318 Obviously there is no technical limitation on the number of branches. You can
319 freely create topic branches off of project branches, or sub projects inside
320 larger projects freely. Such branches should incorporate the name of the branch
321 they were made off so that people don't accidentally assume they should be
324 git checkout -b my-project--topic/foo my-project
326 (unfortunately Git will not allow C<my-project/foo> as a branch name if
327 C<my-project> is a valid ref).
329 =head1 BRANCH ARCHIVAL
331 Merged branches should be deleted.
333 Failed branches may be kept, but should be moved to C<attic/> to differentiate
334 them from in-progress topic branches.
336 Branches that have not been worked on for a long time will be moved to
337 C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
338 if you want to start working on it again.
340 =head1 TESTS, TESTS, TESTS
342 If you write I<any> code for Moose or Class::MOP, you B<must> add
343 tests for that code. If you do not write tests then we cannot
344 guarantee your change will not be removed or altered at a later date,
345 as there is nothing to confirm this is desired behavior.
347 If your code change/addition is deep within the bowels of
348 Moose/Class::MOP and your test exercises this feature in a non-obvious
349 way, please add some comments either near the code in question or in
350 the test so that others know.
352 We also greatly appreciate documentation to go with your changes, and an entry
353 in the Changes file. Make sure to give yourself credit! Major changes or new
354 user-facing features should also be documented in L<Moose::Manual::Delta>.
356 =head1 DOCS, DOCS, DOCS
358 Any user-facing changes must be accompanied by documentation. If you're not
359 comfortable writing docs yourself, you might be able to convince another Moose
362 Our goal is to make sure that all features are documented. Undocumented
363 features are not considered part of the API when it comes to determining
364 whether a change is backwards compatible.
366 =head1 BACKWARDS COMPATIBILITY
368 Change is inevitable, and Moose is not immune to this. We do our best
369 to maintain backwards compatibility, but we do not want the code base
370 to become overburdened by this. This is not to say that we will be
371 frivolous with our changes, quite the opposite, just that we are not
372 afraid of change and will do our best to keep it as painless as
373 possible for the end user.
375 Our policy for handling backwards compatibility is documented in more detail in
376 L<Moose::Manual::Support>.
378 All backwards incompatible changes B<must> be documented in
379 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
380 for the change in that document.
384 Stevan Little E<lt>stevan@iinteractive.comE<gt>
386 Chris (perigrin) Prather
388 Yuval (nothingmuch) Kogman
390 Jesse Luehrs E<lt>doy at tozt dot netE<gt>
392 =head1 COPYRIGHT AND LICENSE
394 Copyright 2009-2010 by Infinity Interactive, Inc.
396 L<http://www.iinteractive.com>
398 This library is free software; you can redistribute it and/or modify
399 it under the same terms as Perl itself.