close over the coercion sub separately
[gitmo/Moose.git] / lib / Moose / Manual / Contributing.pod
1 package Moose::Manual::Contributing;
2
3 # ABSTRACT: How to get involved in Moose
4
5 __END__
6
7 =pod
8
9 =head1 GETTING INVOLVED
10
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
15 review your changes.
16
17 =head1 NEW FEATURES
18
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
22 MooseX module first.
23
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
27 core.
28
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.
32
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.
36
37 =head1 PEOPLE
38
39 As Moose has matured, some structure has emerged in the process.
40
41 =over
42
43 =item Contributors - people creating a topic or branch
44
45 You.
46
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.
50
51 The relevant repository URIs are:
52
53 =over
54
55 =item Read-Only
56
57 L<git://git.moose.perl.org/Moose.git>
58
59 =item Read+Write
60
61 L<gitmo@git.moose.perl.org:Moose.git>
62
63 =back
64
65 =item Cabal - people who can release moose
66
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.
71
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.
74
75 =back
76
77 =head1 BRANCH LAYOUT
78
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.
81
82 =over
83
84 =item stable/*
85
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.
90
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.
94
95 =item master
96
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
101 release.
102
103 =item rfc/*
104
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.
108
109 =item topic/*
110
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.
114
115 =item attic/*
116
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.
119
120 =item abandoned/*
121
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.
124
125 =back
126
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.
131
132 =head1 STANDARD WORKFLOW
133
134     # update your copy of master
135     git checkout master
136     git pull --rebase
137
138     # create a new topic branch
139     git checkout -b topic/my-feature
140
141     # hack, commit, feel free to break fast forward
142     git commit --amend        # allowed
143     git rebase --interactive  # allowed
144     git push --force          # allowed
145
146     # keep the branch rebased on top of master, for easy reviewing
147     git remote update
148     git rebase origin/master
149     git push --force
150
151     # when finished, move the branch to the rfc/ namespace
152     git branch -m rfc/my-feature
153     git push
154     git push origin :topic/my-feature
155
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
159 C<master>.
160
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.
163
164 =head1 APPROVAL WORKFLOW
165
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
170 the master branch.
171
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.
177
178 =over 4
179
180 =item Small bug fixes, doc patches and additional passing tests.
181
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.
185
186 =item Larger bug fixes, doc additions and TODO or failing tests.
187
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.
190
191 New documentation is always welcome, but should also be reviewed by a cabal
192 member for accuracy.
193
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.
197
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.
201
202 =item New user-facing features.
203
204 Anything that creates a new user-visible feature needs to be approved by
205 B<more than one> cabal member.
206
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.
209
210 =item New internals features.
211
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.
214
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
218 branch's approval.
219
220 =item Backwards incompatible changes.
221
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.
225
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
228 defend your change.
229
230 =back
231
232 =head1 RELEASE WORKFLOW
233
234     # major releases (including trial releases)
235     git checkout master
236
237     # minor releases
238     git checkout stable/X.YY
239
240     # do final changelogging, etc
241     vim dist.ini # increment version number
242     git commit
243     dzil release # or dzil release --trial for trial releases
244     git commit # to add the actual release date
245     git branch stable/X.YY # only for non-trial major releases
246
247 =head2 Release How-To
248
249 Moose uses L<Dist::Zilla> to manage releases. Although the git repository comes
250 with a C<Makefile.PL>, it is a very basic one just to allow the basic
251 C<perl Makefile.PL && make && make test> cycle to work. In particular, it
252 doesn't include any release metadata, such as dependencies. In order to get
253 started with Dist::Zilla, first install it: C<cpanm Dist::Zilla>, and then
254 install the plugins necessary for reading the C<dist.ini>:
255 C<dzil authordeps | cpanm>.
256
257 Moose releases fall into two categories, each with their own level of release
258 preparation. A minor release is one which does not include any API changes,
259 deprecations, and so on. In that case, it is sufficient to simply test the
260 release candidate against a few different different Perls. Testing should be
261 done against at least two recent major version of Perl (5.8.8 and 5.10.1, for
262 example). If you have more versions available, you are encouraged to test them
263 all. However, we do not put a lot of effort into supporting older 5.8.x
264 releases.
265
266 For major releases which include an API change or deprecation, you should run
267 the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
268 and other Moose-using modules from CPAN. In order to run this script, you must
269 arrange to have the new version of Moose in Perl's include path. You can use
270 C<prove -b> and C<prove -I>, install the module, or fiddle with the C<PERL5LIB>
271 environment variable, whatever makes you happy.
272
273 This test downloads each module from CPAN, runs its tests, and logs failures
274 and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
275 failures or warnings, please work with the authors of the modules in question
276 to fix them. If the module author simply isn't available or does not want to
277 fix the bug, it is okay to make a release.
278
279 Regardless of whether or not a new module is available, any breakages should
280 be noted in the conflicts list in the distribution's F<dist.ini>.
281
282 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
283
284 The stable branch exists for easily making bug fix releases.
285
286     git remote update
287     git checkout -b topic/my-emergency-fix origin/master
288     # hack
289     git commit
290
291 Then a cabal member merges into C<master>, and backports the change into
292 C<stable/X.YY>:
293
294     git checkout master
295     git merge topic/my-emergency-fix
296     git push
297     git checkout stable/X.YY
298     git cherry-pick -x master
299     git push
300     # release
301
302 =head1 PROJECT WORKFLOW
303
304 For longer lasting branches, we use a subversion style branch layout, where
305 master is routinely merged into the branch. Rebasing is allowed as long as all
306 the branch contributors are using C<git pull --rebase> properly.
307
308 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
309 only be done in topic branches. Committing to master is still done with the
310 same review process as a topic branch, and the branch must merge as a fast
311 forward.
312
313 This is pretty much the way we're doing branches for large-ish things right
314 now.
315
316 Obviously there is no technical limitation on the number of branches. You can
317 freely create topic branches off of project branches, or sub projects inside
318 larger projects freely. Such branches should incorporate the name of the branch
319 they were made off so that people don't accidentally assume they should be
320 merged into master:
321
322     git checkout -b my-project--topic/foo my-project
323
324 (unfortunately Git will not allow C<my-project/foo> as a branch name if
325 C<my-project> is a valid ref).
326
327 =head1 BRANCH ARCHIVAL
328
329 Merged branches should be deleted.
330
331 Failed branches may be kept, but should be moved to C<attic/> to differentiate
332 them from in-progress topic branches.
333
334 Branches that have not been worked on for a long time will be moved to
335 C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
336 if you want to start working on it again.
337
338 =head1 TESTS, TESTS, TESTS
339
340 If you write I<any> code for Moose, you B<must> add tests for that code. If you
341 do not write tests then we cannot guarantee your change will not be removed or
342 altered at a later date, as there is nothing to confirm this is desired
343 behavior.
344
345 If your code change/addition is deep within the bowels of Moose and your test
346 exercises this feature in a non-obvious way, please add some comments either
347 near the code in question or in the test so that others know.
348
349 We also greatly appreciate documentation to go with your changes, and an entry
350 in the Changes file. Make sure to give yourself credit! Major changes or new
351 user-facing features should also be documented in L<Moose::Manual::Delta>.
352
353 =head1 DOCS, DOCS, DOCS
354
355 Any user-facing changes must be accompanied by documentation. If you're not
356 comfortable writing docs yourself, you might be able to convince another Moose
357 dev to help you.
358
359 Our goal is to make sure that all features are documented. Undocumented
360 features are not considered part of the API when it comes to determining
361 whether a change is backwards compatible.
362
363 =head1 BACKWARDS COMPATIBILITY
364
365 Change is inevitable, and Moose is not immune to this. We do our best
366 to maintain backwards compatibility, but we do not want the code base
367 to become overburdened by this. This is not to say that we will be
368 frivolous with our changes, quite the opposite, just that we are not
369 afraid of change and will do our best to keep it as painless as
370 possible for the end user.
371
372 Our policy for handling backwards compatibility is documented in more detail in
373 L<Moose::Manual::Support>.
374
375 All backwards incompatible changes B<must> be documented in
376 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
377 for the change in that document.
378
379 =cut