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, more long term branches can also be created in the root namespace (i.e.
125 at the same level as master and stable). This is more appropriate if multiple
126 people are intending to work on the branch. These branches should not be
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 cabal
220 and agreed to by a majority of the members.
222 We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
223 Moose. If your changes break back-compat, you must be ready to discuss and
228 =head1 RELEASE WORKFLOW
230 # major releases (including trial releases)
236 # edit for final version bumping, changelogging, etc
237 # prepare release (test suite etc)
241 git branch stable/2.XXYY # only for non-trial major releases
242 shipit # does not ship the tarball, but does everything else
245 cpan-upload ~/shipit-dist/Moose-2.XXYY.tar.gz
249 mv Moose-2.XXYY.tar.gz Moose-2.XXYY-TRIAL.tar.gz
250 cpan-upload Moose-2.XXYY-TRIAL.tar.gz
252 =head2 Release How-To
254 Moose (and L<Class::MOP>) releases fall into two categories, each with their
255 own level of release preparation. A minor release is one which does not
256 include any API changes, deprecations, and so on. In that case, it is
257 sufficient to simply test the release candidate against a few different
258 different Perls. Testing should be done against at least two recent major
259 version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
260 available, you are encouraged to test them all. However, we do not put a lot
261 of effort into supporting older 5.8.x releases.
263 For major releases which include an API change or deprecation, you should run
264 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
265 and other Moose-using modules from CPAN. In order to run this script, you must
266 arrange to have the new version of Moose and/or Class::MOP in Perl's include
267 path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle
268 with the C<PERL5LIB> environment variable, whatever makes you happy.
270 This test downloads each module from CPAN, runs its tests, and logs failures
271 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
272 failures or warnings, please work with the authors of the modules in question
273 to fix them. If the module author simply isn't available or does not want to
274 fix the bug, it is okay to make a release.
276 Regardless of whether or not a new module is available, any breakages should
277 be noted in the conflicts list in the distribution's F<Makefile.PL>.
279 Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the
280 release goes smoothly. You are strongly encouraged to use this instead of
281 doing the final release steps by hand.
283 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
285 The stable branch exists for easily making bug fix releases.
288 git checkout -b topic/my-emergency-fix origin/master
292 Then a cabal member merges into C<master>, and backports the change into
296 git merge topic/my-emergency-fix
299 git cherry-pick -x master
303 =head1 PROJECT WORKFLOW
305 For longer lasting branches, we use a subversion style branch layout, where
306 master is routinely merged into the branch. Rebasing is allowed as long as all
307 the branch contributors are using C<git pull --rebase> properly.
309 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
310 only be done in topic branches. Committing to master is still done with the
311 same review process as a topic branch, and the branch must merge as a fast
314 This is pretty much the way we're doing branches for large-ish things right
317 Obviously there is no technical limitation on the number of branches. You can
318 freely create topic branches off of project branches, or sub projects inside
319 larger projects freely. Such branches should incorporate the name of the branch
320 they were made off so that people don't accidentally assume they should be
323 git checkout -b my-project--topic/foo my-project
325 (unfortunately Git will not allow C<my-project/foo> as a branch name if
326 C<my-project> is a valid ref).
328 =head1 BRANCH ARCHIVAL
330 Merged branches should be deleted.
332 Failed branches may be kept, but should be to C<attic/> to differentiate them
333 from in-progress topic branches.
335 Branches that have not been worked on for a long time will be moved to
336 C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
337 if you want to start working on it again.
339 =head1 TESTS, TESTS, TESTS
341 If you write I<any> code for Moose or Class::MOP, you B<must> add
342 tests for that code. If you do not write tests then we cannot
343 guarantee your change will not be removed or altered at a later date,
344 as there is nothing to confirm this is desired behavior.
346 If your code change/addition is deep within the bowels of
347 Moose/Class::MOP and your test exercises this feature in a non-obvious
348 way, please add some comments either near the code in question or in
349 the test so that others know.
351 We also greatly appreciate documentation to go with your changes, and an entry
352 in the Changes file. Make sure to give yourself credit! Major changes or new
353 user-facing features should also be documented in L<Moose::Manual::Delta>.
355 =head1 BACKWARDS COMPATIBILITY
357 Change is inevitable, and Moose is not immune to this. We do our best
358 to maintain backwards compatibility, but we do not want the code base
359 to become overburdened by this. This is not to say that we will be
360 frivolous with our changes, quite the opposite, just that we are not
361 afraid of change and will do our best to keep it as painless as
362 possible for the end user.
364 Our policy for handling backwards compatibility is documented in more detail in
365 L<Moose::Manual::Support>.
367 All backwards incompatible changes B<must> be documented in
368 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
369 for the change in that document.
373 Stevan Little E<lt>stevan@iinteractive.comE<gt>
375 Chris (perigrin) Prather
377 Yuval (nothingmuch) Kogman
379 Jesse Luehrs E<lt>doy at tozt dot netE<gt>
381 =head1 COPYRIGHT AND LICENSE
383 Copyright 2009 by Infinity Interactive, Inc.
385 L<http://www.iinteractive.com>
387 This library is free software; you can redistribute it and/or modify
388 it under the same terms as Perl itself.