1 package Moose::Manual::Contributing;
3 # ABSTRACT: How to get involved in Moose
9 =head1 GETTING INVOLVED
11 Moose is an open project, and we are always willing to accept bug fixes,
12 more tests, and documentation patches. Commit bits are given out freely, and
13 the L</STANDARD WORKFLOW> is very simple. The general gist is: clone the Git
14 repository, create a new topic branch, hack away, then find a committer to
17 Note that this document applies to both Moose and L<Class::MOP> development.
21 Moose already has a fairly large feature set, and we are currently
22 B<not> looking to add any major new features to it. If you have an
23 idea for a new feature in Moose, you are encouraged to create a
26 At this stage, no new features will even be considered for addition
27 into the core without first being vetted as a MooseX module, unless
28 it is absolutely 100% impossible to implement the feature outside the
31 If you think it is 100% impossible, please come discuss it with us on IRC or
32 via e-mail. Your feature may need a small hook in the core, or a
33 refactoring of some core modules, and we are definitely open to that.
35 Moose was built from the ground up with the idea of being highly extensible,
36 and quite often the feature requests we see can be implemented through small
37 extensions. Try it, it's much easier than you might think.
41 As Moose has matured, some structure has emerged in the process.
45 =item Contributors - people creating a topic or branch
49 If you have commit access, you can create a topic on the main Moose.git
50 repository. If you don't have a commit bit, give us your SSH key or create your
51 own clone of the L<git://git.moose.perl.org/Moose.git> repository.
53 The relevant repository URIs are:
59 L<git://git.moose.perl.org/Moose.git>
63 L<gitmo@git.moose.perl.org:Moose.git>
67 =item Cabal - people who can release moose
69 These people are the ones who have co-maint on Moose itself and can create a
70 release. They're listed under L<Moose/CABAL> in the Moose documentation. They
71 are responsible for reviewing branches, and are the only people who are allowed
72 to push to stable branches.
74 Cabal members are listed in L<Moose> and can often be found on irc in the
75 L<irc://irc.perl.org/#moose-dev> channel.
81 The repository is divided into several branches to make maintenance easier for
82 everyone involved. The branches below are ordered by level of stability.
88 The branch from which releases are cut. When making a new major release, the
89 release manager makes a new C<stable/X.YY> branch at the current position of
90 C<master>. The version used in the stable branch should not include the last
91 two digits of the version number.
93 For minor releases, patches will be committed to C<master>, and
94 backported (cherry-picked) to the appropriate stable branch as needed. A
95 stable branch is only updated by someone from the Cabal during a release.
99 The main development branch. All new code should be written against this
100 branch. This branch contains code that has been reviewed, and will be included
101 in the next major release. Commits which are judged to not break backwards
102 compatibility may be backported into C<stable> to be included in the next minor
107 Topic branches that are completed and waiting on review. A Cabal member will
108 look over branches in this namespace, and either merge them to C<master> if
109 they are acceptable, or move them back to a different namespace otherwise.
113 Small personal branches that are still in progress. They can be freely rebased.
114 They contain targeted features that may span a handful of commits. Any change
115 or bugfix should be created in a topic branch.
119 Branches which have been reviewed, and rejected. They remain in the repository
120 in case we later change our mind, or in case parts of them are still useful.
124 Topic branches which have had no activity for a long period of time will be
125 moved here, to keep the main areas clean.
129 Larger, longer term branches can also be created in the root namespace (i.e.
130 at the same level as master and stable). This may be appropriate if multiple
131 people are intending to work on the branch. These branches should not be
132 rebased without checking with other developers first.
134 =head1 STANDARD WORKFLOW
136 # update your copy of master
140 # create a new topic branch
141 git checkout -b topic/my-feature
143 # hack, commit, feel free to break fast forward
144 git commit --amend # allowed
145 git rebase --interactive # allowed
146 git push --force # allowed
148 # keep the branch rebased on top of master, for easy reviewing
150 git rebase origin/master
153 # when finished, move the branch to the rfc/ namespace
154 git branch -m rfc/my-feature
156 git push origin :topic/my-feature
158 When your branch is completed, make sure it has been moved to the C<rfc/>
159 namespace and is rebased on top of master, and ask for review/approval (see
160 L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
163 No actual merging (as in a human resolving conflicts) should be done when
164 merging into C<master>, only from C<master> into other branches.
166 =head1 APPROVAL WORKFLOW
168 Moose is an open project but it is also an increasingly important one. Many
169 modules depend on Moose being stable. Therefore, we have a basic set of
170 criteria for reviewing and merging branches. What follows is a set of rough
171 guidelines that ensures all new code is properly vetted before it is merged to
174 It should be noted that if you want your specific branch to be approved, it is
175 B<your> responsibility to follow this process and advocate for your branch. The
176 preferred way is to send a request to the mailing list for review/approval;
177 this allows us to better keep track of the branches awaiting approval and those
178 which have been approved.
182 =item Small bug fixes, doc patches and additional passing tests.
184 These items don't really require approval beyond one of the core contributors
185 just doing a simple review. For especially simple patches (doc patches
186 especially), committing directly to master is fine.
188 =item Larger bug fixes, doc additions and TODO or failing tests.
190 Larger bug fixes should be reviewed by at least one cabal member and should be
191 tested using the F<xt/author/test-my-dependents.t> test.
193 New documentation is always welcome, but should also be reviewed by a cabal
196 TODO tests are basically feature requests, see our L</NEW FEATURES> section
197 for more information on that. If your feature needs core support, create a
198 C<topic/> branch using the L</STANDARD WORKFLOW> and start hacking away.
200 Failing tests are basically bug reports. You should find a core contributor
201 and/or cabal member to see if it is a real bug, then submit the bug and your
202 test to the RT queue. Source control is not a bug reporting tool.
204 =item New user-facing features.
206 Anything that creates a new user-visible feature needs to be approved by
207 B<more than one> cabal member.
209 Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
210 the guidelines. Do not be surprised if a new feature is rejected for the core.
212 =item New internals features.
214 New features for Moose internals are less restrictive than user facing
215 features, but still require approval by B<at least one> cabal member.
217 Ideally you will have run the F<test-my-dependents.t> script to be sure you
218 are not breaking any MooseX module or causing any other unforeseen havoc. If
219 you do this (rather than make us do it), it will only help to hasten your
222 =item Backwards incompatible changes.
224 Anything that breaks backwards compatibility must be discussed by the
225 cabal. Backwards incompatible changes should not be merged to master if there
226 are strong objections from any cabal members.
228 We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
229 Moose. If your changes break back-compat, you must be ready to discuss and
234 =head1 RELEASE WORKFLOW
236 # major releases (including trial releases)
240 git checkout stable/X.YY
242 # edit for final version bumping, changelogging, etc
243 # prepare release (test suite etc)
247 git branch stable/X.YY # only for non-trial major releases
248 shipit # does not ship the tarball, but does everything else
251 cpan-upload ~/shipit-dist/Moose-X.YYZZ.tar.gz
255 mv Moose-X.YYZZ.tar.gz Moose-X.YYZZ-TRIAL.tar.gz
256 cpan-upload Moose-X.YYZZ-TRIAL.tar.gz
258 =head2 Release How-To
260 Moose (and L<Class::MOP>) releases fall into two categories, each with their
261 own level of release preparation. A minor release is one which does not
262 include any API changes, deprecations, and so on. In that case, it is
263 sufficient to simply test the release candidate against a few different
264 different Perls. Testing should be done against at least two recent major
265 version of Perl (5.8.8 and 5.10.1, for example). If you have more versions
266 available, you are encouraged to test them all. However, we do not put a lot
267 of effort into supporting older 5.8.x releases.
269 For major releases which include an API change or deprecation, you should run
270 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
271 and other Moose-using modules from CPAN. In order to run this script, you must
272 arrange to have the new version of Moose and/or Class::MOP in Perl's include
273 path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle
274 with the C<PERL5LIB> environment variable, whatever makes you happy.
276 This test downloads each module from CPAN, runs its tests, and logs failures
277 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
278 failures or warnings, please work with the authors of the modules in question
279 to fix them. If the module author simply isn't available or does not want to
280 fix the bug, it is okay to make a release.
282 Regardless of whether or not a new module is available, any breakages should
283 be noted in the conflicts list in the distribution's F<Makefile.PL>.
285 Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the
286 release goes smoothly. You are strongly encouraged to use this instead of
287 doing the final release steps by hand.
289 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
291 The stable branch exists for easily making bug fix releases.
294 git checkout -b topic/my-emergency-fix origin/master
298 Then a cabal member merges into C<master>, and backports the change into
302 git merge topic/my-emergency-fix
304 git checkout stable/X.YY
305 git cherry-pick -x master
309 =head1 PROJECT WORKFLOW
311 For longer lasting branches, we use a subversion style branch layout, where
312 master is routinely merged into the branch. Rebasing is allowed as long as all
313 the branch contributors are using C<git pull --rebase> properly.
315 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
316 only be done in topic branches. Committing to master is still done with the
317 same review process as a topic branch, and the branch must merge as a fast
320 This is pretty much the way we're doing branches for large-ish things right
323 Obviously there is no technical limitation on the number of branches. You can
324 freely create topic branches off of project branches, or sub projects inside
325 larger projects freely. Such branches should incorporate the name of the branch
326 they were made off so that people don't accidentally assume they should be
329 git checkout -b my-project--topic/foo my-project
331 (unfortunately Git will not allow C<my-project/foo> as a branch name if
332 C<my-project> is a valid ref).
334 =head1 BRANCH ARCHIVAL
336 Merged branches should be deleted.
338 Failed branches may be kept, but should be moved to C<attic/> to differentiate
339 them from in-progress topic branches.
341 Branches that have not been worked on for a long time will be moved to
342 C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
343 if you want to start working on it again.
345 =head1 TESTS, TESTS, TESTS
347 If you write I<any> code for Moose or Class::MOP, you B<must> add
348 tests for that code. If you do not write tests then we cannot
349 guarantee your change will not be removed or altered at a later date,
350 as there is nothing to confirm this is desired behavior.
352 If your code change/addition is deep within the bowels of
353 Moose/Class::MOP and your test exercises this feature in a non-obvious
354 way, please add some comments either near the code in question or in
355 the test so that others know.
357 We also greatly appreciate documentation to go with your changes, and an entry
358 in the Changes file. Make sure to give yourself credit! Major changes or new
359 user-facing features should also be documented in L<Moose::Manual::Delta>.
361 =head1 DOCS, DOCS, DOCS
363 Any user-facing changes must be accompanied by documentation. If you're not
364 comfortable writing docs yourself, you might be able to convince another Moose
367 Our goal is to make sure that all features are documented. Undocumented
368 features are not considered part of the API when it comes to determining
369 whether a change is backwards compatible.
371 =head1 BACKWARDS COMPATIBILITY
373 Change is inevitable, and Moose is not immune to this. We do our best
374 to maintain backwards compatibility, but we do not want the code base
375 to become overburdened by this. This is not to say that we will be
376 frivolous with our changes, quite the opposite, just that we are not
377 afraid of change and will do our best to keep it as painless as
378 possible for the end user.
380 Our policy for handling backwards compatibility is documented in more detail in
381 L<Moose::Manual::Support>.
383 All backwards incompatible changes B<must> be documented in
384 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
385 for the change in that document.