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 Core Committers - people reviewing and merging a branch
67 These people have worked with the Moose codebase for a while.
69 They've been responsible for large features or branches and can help review
70 your changes and apply them to the master branch using the basic
71 L</APPROVAL WORKFLOW>.
73 They are also fairly well versed in Git, in order to merge the branches with
74 no mistakes (especially when the merge fails), and to provide advice to
77 =item Cabal - people who can release moose
79 These people are the ones who have co-maint on Moose itself and can create a
80 release. They're listed under L<Moose/CABAL> in the Moose documentation. They
81 merge from Master to Stable.
87 The repository is divided into several branches to make maintenance easier for
88 everyone involved. The branches below are ordered by level of stability.
94 The branch from which releases are cut. When making a new major release, the
95 release manager makes a new C<stable/X.YY> branch at the current position of
96 C<master>. The version used in the stable branch should not include the last
97 two digits of the version number.
99 For minor releases, patches will be committed to C<master>, and
100 backported (cherry-picked) to the appropriate stable branch as needed. A
101 stable branch is only updated by someone from the Cabal during a release.
103 The branch from which releases are cut. When making a new release, the
104 release manager merges from master to stable. The stable branch is only
105 updated by someone from the Cabal during a release.
107 =item Master (refs/heads/master)
109 The branch for new development. This branch is merged into and branched from.
111 =item Branches (refs/heads/*)
113 Large community branches for big development "projects".
115 =item Topics (refs/heads/topic/*)
117 Small personal branches that have been published for review, but can get
118 freely rebased. Targeted features that may span a handful of commits.
120 Any change or bugfix should be created in a topic branch.
124 =head1 STANDARD WORKFLOW
126 # update your copy of master
130 # create a new topic branch
131 git checkout -b topic/my-feature origin/master
133 # hack, commit, feel free to break fast forward
134 git commit --amend # allowed
135 git rebase --interactive # allowed
136 git push --force origin topic/my_feature # allowed
138 Then ask for a review/approval (see L</APPROVAL WORKFLOW>), and merge
139 to master. If it merges cleanly and nobody has any objections, then it
140 can be pushed to master.
142 If it doesn't merge as a fast forward, the author of the branch needs to run
145 git rebase origin/master # or merge
147 and bring the branch up to date, so that it can be merged as a fast forward
150 No actual merging (as in a human resolving conflicts) should be done when
151 merging into master, only from master into other branches.
153 =head2 Preparing a topic branch
155 Before a merge, a topic branch can be cleaned up by the author.
157 This can be done using interactive rebase to combine commits, etc, or even
158 C<git merge --squash> to make the whole topic into a single commit.
160 Structuring changes like this makes it easier to apply git revert at a later
161 date, and encourages a clean and descriptive history that documents what the
162 author was trying to do, without the various hangups that happened while they
163 were trying to do it (commits like "oops forgot that file" are not only
164 unnecessary noise, they also make running things like git bisect or git revert
167 However, by far the biggest benefit is that the number of commits that go into
168 master is eventually reduced, and they are simple and coherent, making it much
169 easier for people maintaining branches to stay up to date.
171 All large changes should be documented in L<Moose::Manual::Delta>.
173 =head1 APPROVAL WORKFLOW
175 Moose is an open project but it is also an increasingly important one. Many
176 modules depend on Moose being stable. Therefore, we have a basic set of
177 criteria for reviewing and merging branches. What follows is a set of rough
178 guidelines that ensures all new code is properly vetted before it is merged to
181 It should be noted that if you want your specific branch to be approved, it is
182 B<your> responsibility to follow this process and advocate for your branch.
183 The preferred way is to send a request to the mailing list for review/approval,
184 this allows us to better keep track of the branches awaiting approval and those
185 which have been approved.
189 =item Small bug fixes, doc patches and additional passing tests.
191 These items don't really require approval beyond one of the core contributors
192 just doing a simple review.
194 =item Larger bug fixes, doc additions and TODO or failing tests.
196 Larger bug fixes should be reviewed by at least one cabal member and should be
197 tested using the F<xt/author/test-my-dependents.t> test.
199 New documentation is always welcome, but should also be reviewed by a cabal
202 TODO tests are basically feature requests, see our L</NEW FEATURES> section
203 for more information on that. If your feature needs core support, create a
204 topic/ branch using the L</STANDARD WORKFLOW> and start hacking away.
206 Failing tests are basically bug reports. You should find a core contributor
207 and/or cabal member to see if it is a real bug, then submit the bug and your
208 test to the RT queue. Source control is not a bug reporting tool.
210 =item New user-facing features.
212 Anything that creates a new user-visible feature needs to be approved by
213 B<more than one> cabal member.
215 Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
216 the guidelines. Do not be surprised if a new feature is rejected for the core.
218 =item New internals features.
220 New features for Moose internals are less restrictive than user facing
221 features, but still require approval by B<at least one> cabal member.
223 Ideally you will have run the F<test-my-dependents.t> script to be sure you
224 are not breaking any MooseX module or causing any other unforeseen havoc. If
225 you do this (rather than make us do it), it will only help to hasten your
228 =item Backwards incompatible changes.
230 Anything that breaks backwards compatibility must be discussed by the
231 cabal. Backwards incompatible changes should not be merged to master if there
232 are strong objections for any cabal members.
234 We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
235 Moose. If your changes break back-compat, you must be ready to discuss and
240 =head1 RELEASE WORKFLOW
245 git checkout stable/X.YY
247 # edit for final version bumping, changelogging, etc
248 # prepare release (test suite etc)
252 git branch stable/X.YY # only for non-trial major releases
253 shipit # does not ship the tarball, but does everything else
254 cpan-upload ~/shipit-dist/Moose-X.YZ.tar.gz
256 Development releases are made without merging into the stable branch.
259 cpan-upload ~/shipit-dist/Moose-X.YYZZ.tar.gz
263 mv Moose-X.YYZZ.tar.gz Moose-X.YYZZ-TRIAL.tar.gz
264 cpan-upload Moose-X.YYZZ-TRIAL.tar.gz
266 =head2 Release How-To
268 Moose (and L<Class::MOP>) releases fall into two categories, each with their
269 own level of release preparation. A minor release is one which does not
270 include any API changes, deprecations, and so on. In that case, it is
271 sufficient to simply test the release candidate against a few different
272 different Perls. Testing should be done against at least two recent major
273 version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
274 available, you are encouraged to test them all. However, we do not put a lot
275 of effort into supporting older 5.8.x releases.
277 For major releases which include an API change or deprecation, you should run
278 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
279 and other Moose-using modules from CPAN. In order to run this script, you must
280 arrange to have the new version of Moose and/or Class::MOP in Perl's include
281 path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle
282 with the C<PERL5LIB> environment variable, whatever makes you happy.
284 This test downloads each module from CPAN, runs its tests, and logs failures
285 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
286 failures or warnings, please work with the authors of the modules in question
287 to fix them. If the module author simply isn't available or does not want to
288 fix the bug, it is okay to make a release.
290 Regardless of whether or not a new module is available, any breakages should
291 be noted in the conflicts list in the distribution's F<Makefile.PL>.
293 Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the
294 release goes smoothly. You are strongly encouraged to use this instead of
295 doing the final release steps by hand.
297 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
299 Anyone can create the necessary fix by branching off of the stable branch:
302 git checkout -b topic/my-emergency-fix origin/stable
306 Then a cabal member merges into C<master>, and backports the change into
310 git merge topic/my-emergency-fix
312 git checkout stable/X.YY
313 git cherry-pick -x master
315 =head1 PROJECT WORKFLOW
317 For longer lasting branches, we use a subversion style branch layout, where
318 master is routinely merged into the branch. Rebasing is allowed as long as all
319 the branch contributors are using C<git pull --rebase> properly.
321 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
322 only be done in topic branches. Committing to master is still done with the
323 same review process as a topic branch, and the branch must merge as a fast
326 This is pretty much the way we're doing branches for large-ish things right
329 Obviously there is no technical limitation on the number of branches. You can
330 freely create topic branches off of project branches, or sub projects inside
331 larger projects freely. Such branches should incorporate the name of the branch
332 they were made off so that people don't accidentally assume they should be
335 git checkout -b my-project--topic/foo my-project
337 (unfortunately Git will not allow C<my-project/foo> as a branch name if
338 C<my-project> is a valid ref).
340 =head1 THE "PU" BRANCH
342 To make things easier for longer lived branches (whether topics or projects),
343 the 'pu' branch is basically what happens if you merge all of the branches and
344 topics together with master.
346 We can update this as necessary (e.g. on a weekly basis if there is merit),
347 notifying the authors of the respective branches if their branches did not merge
354 git reset --hard origin/master
355 git merge @all_the_branches
357 If the merge is clean, 'pu' is updated with C<push --force>.
359 If the merge is not clean, the offending branch is removed from
360 C<@all_the_branches>, with a small note of the conflict, and we try again.
362 The authors of the failed branches should be told to try to merge their branch
363 into 'pu', to see how their branch interacts with other branches.
365 'pu' is probably broken most of the time, but lets us know how the different
368 =head1 BRANCH ARCHIVAL
370 Merged branches should be deleted.
372 Failed branches may be kept, but consider moving to refs/attic/ (e.g.
373 http://danns.co.uk/node/295) to keep git branch -l current.
375 Branches that have not been worked on for a long time will be moved to
376 refs/abandoned/ periodically, but feel free to move the branch back to
377 refs/topic/ if you want to start working on it again.
379 =head1 TESTS, TESTS, TESTS
381 If you write I<any> code for Moose or Class::MOP, you B<must> add
382 tests for that code. If you do not write tests then we cannot
383 guarantee your change will not be removed or altered at a later date,
384 as there is nothing to confirm this is desired behavior.
386 If your code change/addition is deep within the bowels of
387 Moose/Class::MOP and your test exercises this feature in a non-obvious
388 way, please add some comments either near the code in question or in
389 the test so that others know.
391 We also greatly appreciate documentation to go with your changes, and
392 an entry in the Changes file. Make sure to give yourself credit!
394 =head1 BACKWARDS COMPATIBILITY
396 Change is inevitable, and Moose is not immune to this. We do our best
397 to maintain backwards compatibility, but we do not want the code base
398 to become overburdened by this. This is not to say that we will be
399 frivolous with our changes, quite the opposite, just that we are not
400 afraid of change and will do our best to keep it as painless as
401 possible for the end user.
403 The rule is that if you do something that is not backwards compatible, you
404 B<must> do I<at least> one deprecation cycle (more if it is larger change).
405 For really larger or radical changes dev releases may be needed as well (the
406 Cabal will decide on this on a case-per-case basis).
408 Our policy with deprecation is that each deprecation should go through several
409 stages. First, we simply add a deprecation notice the documentation in
410 F<Changes> and L<Moose::Manual::Delta>. In a future release, we then make the
411 deprecated feature warn loudly and often so that users will have time to fix
412 their usages. Finally, the feature is removed in a later release.
414 All backwards incompatible changes B<must> be documented in
415 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
416 for the change in that document.
420 Stevan Little E<lt>stevan@iinteractive.comE<gt>
422 Chris (perigrin) Prather
424 Yuval (nothingmuch) Kogman
426 =head1 COPYRIGHT AND LICENSE
428 Copyright 2009-2010 by Infinity Interactive, Inc.
430 L<http://www.iinteractive.com>
432 This library is free software; you can redistribute it and/or modify
433 it under the same terms as Perl itself.