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