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.
76 The repository is divided into several branches to make maintenance easier for
77 everyone involved. The branches below are ordered by level of stability.
83 The branch from which releases are cut. When making a new major release, the
84 release manager makes a new C<stable/$version> branch at the current position
85 of C<master>. For minor releases, patches will be committed to C<master>, and
86 backported (cherry-picked) to the appropriate stable branch as needed. The
87 C<stable> branch is only updated by someone from the Cabal during a release.
91 The main development branch. All new code should be written against this
92 branch. This branch contains code that has been reviewed, and will be included
93 in the next major release. Commits which are judged to not break backwards
94 compatibility may be backported into C<stable> to be included in the next minor
99 Topic branches that are completed and waiting on review. A Cabal member will
100 look over branches in this namespace, and either merge them to C<master> if
101 they are acceptable, or move them back to a different namespace otherwise.
105 Small personal branches that are still in progress. They can be freely rebased.
106 They contain targeted features that may span a handful of commits. Any change
107 or bugfix should be created in a topic branch.
111 Branches which have been reviewed, and rejected. They remain in the repository
112 in case we later change our mind, or in case parts of them are still useful.
116 Topic branches which have had no activity for a long period of time will be
117 moved here, to keep the main areas clean.
121 Larger, more long term branches can also be created in the root namespace (i.e.
122 at the same level as master and stable). This is more appropriate if multiple
123 people are intending to work on the branch. These branches should not be
126 =head1 STANDARD WORKFLOW
128 # update your copy of master
132 # create a new topic branch
133 git checkout -b topic/my-feature
135 # hack, commit, feel free to break fast forward
136 git commit --amend # allowed
137 git rebase --interactive # allowed
138 git push --force # allowed
140 # keep the branch rebased on top of master, for easy reviewing
142 git rebase origin/master
145 # when finished, move the branch to the rfc/ namespace
146 git branch -m rfc/my-feature
148 git push origin :topic/my-feature
150 When your branch is completed, make sure it has been moved to the C<rfc/>
151 namespace and is rebased on top of master, and ask for review/approval (see
152 L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
155 No actual merging (as in a human resolving conflicts) should be done when
156 merging into C<master>, only from C<master> into other branches.
158 =head1 APPROVAL WORKFLOW
160 Moose is an open project but it is also an increasingly important one. Many
161 modules depend on Moose being stable. Therefore, we have a basic set of
162 criteria for reviewing and merging branches. What follows is a set of rough
163 guidelines that ensures all new code is properly vetted before it is merged to
166 It should be noted that if you want your specific branch to be approved, it is
167 B<your> responsibility to follow this process and advocate for your branch. The
168 preferred way is to send a request to the mailing list for review/approval;
169 this allows us to better keep track of the branches awaiting approval and those
170 which have been approved.
174 =item Small bug fixes, doc patches and additional passing tests.
176 These items don't really require approval beyond one of the core contributors
177 just doing a simple review. For especially simple patches (doc patches
178 especially), committing directly to master is fine.
180 =item Larger bug fixes, doc additions and TODO or failing tests.
182 Larger bug fixes should be reviewed by at least one cabal member and should be
183 tested using the F<xt/author/test-my-dependents.t> test.
185 New documentation is always welcome, but should also be reviewed by a cabal
188 TODO tests are basically feature requests, see our L</NEW FEATURES> section
189 for more information on that. If your feature needs core support, create a
190 C<topic/> branch using the L</STANDARD WORKFLOW> and start hacking away.
192 Failing tests are basically bug reports. You should find a core contributor
193 and/or cabal member to see if it is a real bug, then submit the bug and your
194 test to the RT queue. Source control is not a bug reporting tool.
196 =item New user-facing features.
198 Anything that creates a new user-visible feature needs to be approved by
199 B<more than one> cabal member.
201 Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
202 the guidelines. Do not be surprised if a new feature is rejected for the core.
204 =item New internals features.
206 New features for Moose internals are less restrictive than user facing
207 features, but still require approval by B<at least one> cabal member.
209 Ideally you will have run the F<test-my-dependents.t> script to be sure you
210 are not breaking any MooseX module or causing any other unforeseen havoc. If
211 you do this (rather than make us do it), it will only help to hasten your
214 =item Backwards incompatible changes.
216 Anything that breaks backwards compatibility must be discussed by the cabal
217 and agreed to by a majority of the members.
219 We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
220 Moose. If your changes break back-compat, you must be ready to discuss and
225 =head1 RELEASE WORKFLOW
227 # major releases (including trial releases)
233 # edit for final version bumping, changelogging, etc
234 # prepare release (test suite etc)
238 git branch stable/2.XXYY # only for non-trial major releases
239 shipit # does not ship the tarball, but does everything else
242 cpan-upload ~/shipit-dist/Moose-2.XXYY.tar.gz
246 mv Moose-2.XXYY.tar.gz Moose-2.XXYY-TRIAL.tar.gz
247 cpan-upload Moose-2.XXYY-TRIAL.tar.gz
249 =head2 Release How-To
251 Moose (and L<Class::MOP>) releases fall into two categories, each with their
252 own level of release preparation. A minor release is one which does not
253 include any API changes, deprecations, and so on. In that case, it is
254 sufficient to simply test the release candidate against a few different
255 different Perls. Testing should be done against at least two recent major
256 version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
257 available, you are encouraged to test them all. However, we do not put a lot
258 of effort into supporting older 5.8.x releases.
260 For major releases which include an API change or deprecation, you should run
261 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
262 and other Moose-using modules from CPAN. In order to run this script, you must
263 arrange to have the new version of Moose and/or Class::MOP in Perl's include
264 path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle
265 with the C<PERL5LIB> environment variable, whatever makes you happy.
267 This test downloads each module from CPAN, runs its tests, and logs failures
268 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
269 failures or warnings, please work with the authors of the modules in question
270 to fix them. If the module author simply isn't available or does not want to
271 fix the bug, it is okay to make a release.
273 Regardless of whether or not a new module is available, any breakages should
274 be noted in the conflicts list in the distribution's F<Makefile.PL>.
276 Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the
277 release goes smoothly. You are strongly encouraged to use this instead of
278 doing the final release steps by hand.
280 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
282 The stable branch exists for easily making bug fix releases.
285 git checkout -b topic/my-emergency-fix origin/master
289 Then a cabal member merges into C<master>, and backports the change into
293 git merge topic/my-emergency-fix
296 git cherry-pick -x master
300 =head1 PROJECT WORKFLOW
302 For longer lasting branches, we use a subversion style branch layout, where
303 master is routinely merged into the branch. Rebasing is allowed as long as all
304 the branch contributors are using C<git pull --rebase> properly.
306 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
307 only be done in topic branches. Committing to master is still done with the
308 same review process as a topic branch, and the branch must merge as a fast
311 This is pretty much the way we're doing branches for large-ish things right
314 Obviously there is no technical limitation on the number of branches. You can
315 freely create topic branches off of project branches, or sub projects inside
316 larger projects freely. Such branches should incorporate the name of the branch
317 they were made off so that people don't accidentally assume they should be
320 git checkout -b my-project--topic/foo my-project
322 (unfortunately Git will not allow C<my-project/foo> as a branch name if
323 C<my-project> is a valid ref).
325 =head1 BRANCH ARCHIVAL
327 Merged branches should be deleted.
329 Failed branches may be kept, but should be to C<attic/> to differentiate them
330 from in-progress topic branches.
332 Branches that have not been worked on for a long time will be moved to
333 C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
334 if you want to start working on it again.
336 =head1 TESTS, TESTS, TESTS
338 If you write I<any> code for Moose or Class::MOP, you B<must> add
339 tests for that code. If you do not write tests then we cannot
340 guarantee your change will not be removed or altered at a later date,
341 as there is nothing to confirm this is desired behavior.
343 If your code change/addition is deep within the bowels of
344 Moose/Class::MOP and your test exercises this feature in a non-obvious
345 way, please add some comments either near the code in question or in
346 the test so that others know.
348 We also greatly appreciate documentation to go with your changes, and an entry
349 in the Changes file. Make sure to give yourself credit! Major changes or new
350 user-facing features should also be documented in L<Moose::Manual::Delta>.
352 =head1 BACKWARDS COMPATIBILITY
354 Change is inevitable, and Moose is not immune to this. We do our best
355 to maintain backwards compatibility, but we do not want the code base
356 to become overburdened by this. This is not to say that we will be
357 frivolous with our changes, quite the opposite, just that we are not
358 afraid of change and will do our best to keep it as painless as
359 possible for the end user.
361 Our policy for handling backwards compatibility is documented in more detail in
362 L<Moose::Manual::Support>.
364 All backwards incompatible changes B<must> be documented in
365 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
366 for the change in that document.
370 Stevan Little E<lt>stevan@iinteractive.comE<gt>
372 Chris (perigrin) Prather
374 Yuval (nothingmuch) Kogman
376 Jesse Luehrs E<lt>doy at tozt dot netE<gt>
378 =head1 COPYRIGHT AND LICENSE
380 Copyright 2009 by Infinity Interactive, Inc.
382 L<http://www.iinteractive.com>
384 This library is free software; you can redistribute it and/or modify
385 it under the same terms as Perl itself.