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
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 Cabal - people who can release moose
45 These people are the ones who have co-maint on Moose itself and can create a
46 release. They're listed under L<Moose/CABAL> in the Moose documentation. They
47 are responsible for reviewing branches, and are the only people who are allowed
48 to push to stable branches.
50 Cabal members are listed in L<Moose> and can often be found on irc in the
51 L<irc://irc.perl.org/#moose-dev> channel.
53 =item Contributors - people creating a topic or branch
57 The easiest way to submit a patch is to submit a pull request through Github.
58 You can fork the Moose repository at C<git@github.com:moose/moose.git>. If you
59 would prefer not to use Github, come talk to us at C<#moose> on C<irc.perl.org>
60 and we can work something out.
66 The repository is divided into several branches to make maintenance easier for
67 everyone involved. The branches below are ordered by level of stability.
73 The branch from which releases are cut. When making a new major release, the
74 release manager makes a new C<stable/X.YY> branch at the current position of
75 C<master>. The version used in the stable branch should not include the last
76 two digits of the version number.
78 For minor releases, patches will be committed to C<master>, and
79 backported (cherry-picked) to the appropriate stable branch as needed. A
80 stable branch is only updated by someone from the Cabal during a release.
84 The main development branch. All new code should be written against this
85 branch. This branch contains code that has been reviewed, and will be included
86 in the next major release. Commits which are judged to not break backwards
87 compatibility may be backported into C<stable> to be included in the next minor
92 Topic branches that are completed and waiting on review. A Cabal member will
93 look over branches in this namespace, and either merge them to C<master> if
94 they are acceptable, or move them back to a different namespace otherwise.
98 Small personal branches that are still in progress. They can be freely rebased.
99 They contain targeted features that may span a handful of commits. Any change
100 or bugfix should be created in a topic branch.
104 Branches which have been reviewed, and rejected. They remain in the repository
105 in case we later change our mind, or in case parts of them are still useful.
109 Topic branches which have had no activity for a long period of time will be
110 moved here, to keep the main areas clean.
114 Larger, longer term branches can also be created in the root namespace (i.e.
115 at the same level as master and stable). This may be appropriate if multiple
116 people are intending to work on the branch. These branches should not be
117 rebased without checking with other developers first.
119 =head1 STANDARD WORKFLOW
121 # update your copy of master
125 # create a new topic branch
126 git checkout -b topic/my-feature
128 # hack, commit, feel free to break fast forward
129 git commit --amend # allowed
130 git rebase --interactive # allowed
131 git push --force # allowed
133 # keep the branch rebased on top of master, for easy reviewing
135 git rebase origin/master
138 # when finished, move the branch to the rfc/ namespace
139 git branch -m rfc/my-feature
141 git push origin :topic/my-feature
143 When your branch is completed, make sure it has been moved to the C<rfc/>
144 namespace and is rebased on top of master, and ask for review/approval (see
145 L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
148 No actual merging (as in a human resolving conflicts) should be done when
149 merging into C<master>, only from C<master> into other branches.
151 =head1 APPROVAL WORKFLOW
153 Moose is an open project but it is also an increasingly important one. Many
154 modules depend on Moose being stable. Therefore, we have a basic set of
155 criteria for reviewing and merging branches. What follows is a set of rough
156 guidelines that ensures all new code is properly vetted before it is merged to
159 It should be noted that if you want your specific branch to be approved, it is
160 B<your> responsibility to follow this process and advocate for your branch. The
161 preferred way is to send a request to the mailing list for review/approval;
162 this allows us to better keep track of the branches awaiting approval and those
163 which have been approved.
167 =item Small bug fixes, doc patches and additional passing tests.
169 These items don't really require approval beyond one of the core contributors
170 just doing a simple review. For especially simple patches (doc patches
171 especially), committing directly to master is fine.
173 =item Larger bug fixes, doc additions and TODO or failing tests.
175 Larger bug fixes should be reviewed by at least one cabal member and should be
176 tested using the F<xt/author/test-my-dependents.t> test.
178 New documentation is always welcome, but should also be reviewed by a cabal
181 TODO tests are basically feature requests, see our L</NEW FEATURES> section
182 for more information on that. If your feature needs core support, create a
183 C<topic/> branch using the L</STANDARD WORKFLOW> and start hacking away.
185 Failing tests are basically bug reports. You should find a core contributor
186 and/or cabal member to see if it is a real bug, then submit the bug and your
187 test to the RT queue. Source control is not a bug reporting tool.
189 =item New user-facing features.
191 Anything that creates a new user-visible feature needs to be approved by
192 B<more than one> cabal member.
194 Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
195 the guidelines. Do not be surprised if a new feature is rejected for the core.
197 =item New internals features.
199 New features for Moose internals are less restrictive than user facing
200 features, but still require approval by B<at least one> cabal member.
202 Ideally you will have run the F<test-my-dependents.t> script to be sure you
203 are not breaking any MooseX module or causing any other unforeseen havoc. If
204 you do this (rather than make us do it), it will only help to hasten your
207 =item Backwards incompatible changes.
209 Anything that breaks backwards compatibility must be discussed by the
210 cabal. Backwards incompatible changes should not be merged to master if there
211 are strong objections from any cabal members.
213 We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
214 Moose. If your changes break back-compat, you must be ready to discuss and
219 =head1 RELEASE WORKFLOW
221 # major releases (including trial releases)
225 git checkout stable/X.YY
227 # do final changelogging, etc
228 vim dist.ini # increment version number
230 dzil release # or dzil release --trial for trial releases
231 git commit # to add the actual release date
232 git branch stable/X.YY # only for non-trial major releases
234 =head2 Release How-To
236 Moose uses L<Dist::Zilla> to manage releases. Although the git repository comes
237 with a C<Makefile.PL>, it is a very basic one just to allow the basic
238 C<perl Makefile.PL && make && make test> cycle to work. In particular, it
239 doesn't include any release metadata, such as dependencies. In order to get
240 started with Dist::Zilla, first install it: C<cpanm Dist::Zilla>, and then
241 install the plugins necessary for reading the C<dist.ini>:
242 C<dzil authordeps | cpanm>.
244 Moose releases fall into two categories, each with their own level of release
245 preparation. A minor release is one which does not include any API changes,
246 deprecations, and so on. In that case, it is sufficient to simply test the
247 release candidate against a few different different Perls. Testing should be
248 done against at least two recent major version of Perl (5.8.8 and 5.10.1, for
249 example). If you have more versions available, you are encouraged to test them
250 all. However, we do not put a lot of effort into supporting older 5.8.x
253 For major releases which include an API change or deprecation, you should run
254 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
255 and other Moose-using modules from CPAN. In order to run this script, you must
256 arrange to have the new version of Moose in Perl's include path. You can use
257 C<prove -b> and C<prove -I>, install the module, or fiddle with the C<PERL5LIB>
258 environment variable, whatever makes you happy.
260 This test downloads each module from CPAN, runs its tests, and logs failures
261 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
262 failures or warnings, please work with the authors of the modules in question
263 to fix them. If the module author simply isn't available or does not want to
264 fix the bug, it is okay to make a release.
266 Regardless of whether or not a new module is available, any breakages should
267 be noted in the conflicts list in the distribution's F<dist.ini>.
269 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
271 The stable branch exists for easily making bug fix releases.
274 git checkout -b topic/my-emergency-fix origin/master
278 Then a cabal member merges into C<master>, and backports the change into
282 git merge topic/my-emergency-fix
284 git checkout stable/X.YY
285 git cherry-pick -x master
289 =head1 PROJECT WORKFLOW
291 For longer lasting branches, we use a subversion style branch layout, where
292 master is routinely merged into the branch. Rebasing is allowed as long as all
293 the branch contributors are using C<git pull --rebase> properly.
295 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
296 only be done in topic branches. Committing to master is still done with the
297 same review process as a topic branch, and the branch must merge as a fast
300 This is pretty much the way we're doing branches for large-ish things right
303 Obviously there is no technical limitation on the number of branches. You can
304 freely create topic branches off of project branches, or sub projects inside
305 larger projects freely. Such branches should incorporate the name of the branch
306 they were made off so that people don't accidentally assume they should be
309 git checkout -b my-project--topic/foo my-project
311 (unfortunately Git will not allow C<my-project/foo> as a branch name if
312 C<my-project> is a valid ref).
314 =head1 BRANCH ARCHIVAL
316 Merged branches should be deleted.
318 Failed branches may be kept, but should be moved to C<attic/> to differentiate
319 them from in-progress topic branches.
321 Branches that have not been worked on for a long time will be moved to
322 C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
323 if you want to start working on it again.
325 =head1 TESTS, TESTS, TESTS
327 If you write I<any> code for Moose, you B<must> add tests for that code. If you
328 do not write tests then we cannot guarantee your change will not be removed or
329 altered at a later date, as there is nothing to confirm this is desired
332 If your code change/addition is deep within the bowels of Moose and your test
333 exercises this feature in a non-obvious way, please add some comments either
334 near the code in question or in the test so that others know.
336 We also greatly appreciate documentation to go with your changes, and an entry
337 in the Changes file. Make sure to give yourself credit! Major changes or new
338 user-facing features should also be documented in L<Moose::Manual::Delta>.
340 =head1 DOCS, DOCS, DOCS
342 Any user-facing changes must be accompanied by documentation. If you're not
343 comfortable writing docs yourself, you might be able to convince another Moose
346 Our goal is to make sure that all features are documented. Undocumented
347 features are not considered part of the API when it comes to determining
348 whether a change is backwards compatible.
350 =head1 BACKWARDS COMPATIBILITY
352 Change is inevitable, and Moose is not immune to this. We do our best
353 to maintain backwards compatibility, but we do not want the code base
354 to become overburdened by this. This is not to say that we will be
355 frivolous with our changes, quite the opposite, just that we are not
356 afraid of change and will do our best to keep it as painless as
357 possible for the end user.
359 Our policy for handling backwards compatibility is documented in more detail in
360 L<Moose::Manual::Support>.
362 All backwards incompatible changes B<must> be documented in
363 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
364 for the change in that document.