Commit | Line | Data |
600f7f85 |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Manual::Contributing - How to get involved in Moose |
6 | |
7 | =head1 GETTING INVOLVED |
8 | |
04437dba |
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 |
13 | review your changes. |
600f7f85 |
14 | |
6c1fa4ad |
15 | Note that this document applies to both Moose and L<Class::MOP> development. |
16 | |
600f7f85 |
17 | =head1 NEW FEATURES |
18 | |
04437dba |
19 | Moose already has a fairly large feature set, and we are currently |
d85337ff |
20 | B<not> looking to add any major new features to it. If you have an |
482cc243 |
21 | idea for a new feature in Moose, you are encouraged to create a |
d85337ff |
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. |
600f7f85 |
28 | |
04437dba |
29 | If you think it is 100% impossible, please come discuss it with us on IRC or |
482cc243 |
30 | via e-mail. Your feature may need a small hook in the core, or a |
04437dba |
31 | refactoring of some core modules, and we are definitely open to that. |
d85337ff |
32 | |
482cc243 |
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. |
600f7f85 |
36 | |
04437dba |
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 | |
37a2fef8 |
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. |
04437dba |
50 | |
76127c77 |
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 | |
04437dba |
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 |
4c0880b2 |
69 | are responsible for reviewing branches, and are the only people who are allowed |
70 | to push to stable branches. |
04437dba |
71 | |
794c5045 |
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 | |
04437dba |
75 | =back |
76 | |
77 | =head1 BRANCH LAYOUT |
78 | |
5af926eb |
79 | The repository is divided into several branches to make maintenance easier for |
04437dba |
80 | everyone involved. The branches below are ordered by level of stability. |
81 | |
82 | =over |
83 | |
4c0880b2 |
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/$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. |
04437dba |
91 | |
4c0880b2 |
92 | =item master |
04437dba |
93 | |
4c0880b2 |
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 |
98 | release. |
04437dba |
99 | |
4c0880b2 |
100 | =item rfc/* |
04437dba |
101 | |
4c0880b2 |
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. |
04437dba |
105 | |
4c0880b2 |
106 | =item topic/* |
04437dba |
107 | |
4c0880b2 |
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. |
04437dba |
111 | |
4c0880b2 |
112 | =item attic/* |
04437dba |
113 | |
4c0880b2 |
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. |
116 | |
117 | =item abandoned/* |
118 | |
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. |
04437dba |
121 | |
122 | =back |
123 | |
daae2c87 |
124 | Larger, longer term branches can also be created in the root namespace (i.e. |
125 | at the same level as master and stable). This may be appropriate if multiple |
4c0880b2 |
126 | people are intending to work on the branch. These branches should not be |
daae2c87 |
127 | rebased without checking with other developers first. |
4c0880b2 |
128 | |
04437dba |
129 | =head1 STANDARD WORKFLOW |
130 | |
131 | # update your copy of master |
132 | git checkout master |
133 | git pull --rebase |
134 | |
135 | # create a new topic branch |
4c0880b2 |
136 | git checkout -b topic/my-feature |
04437dba |
137 | |
138 | # hack, commit, feel free to break fast forward |
4c0880b2 |
139 | git commit --amend # allowed |
140 | git rebase --interactive # allowed |
141 | git push --force # allowed |
04437dba |
142 | |
4c0880b2 |
143 | # keep the branch rebased on top of master, for easy reviewing |
04437dba |
144 | git remote update |
4c0880b2 |
145 | git rebase origin/master |
146 | git push --force |
04437dba |
147 | |
4c0880b2 |
148 | # when finished, move the branch to the rfc/ namespace |
149 | git branch -m rfc/my-feature |
150 | git push |
151 | git push origin :topic/my-feature |
04437dba |
152 | |
4c0880b2 |
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 |
156 | C<master>. |
04437dba |
157 | |
4c0880b2 |
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. |
04437dba |
160 | |
fbfcdc75 |
161 | =head1 APPROVAL WORKFLOW |
162 | |
0b81ea16 |
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 |
167 | the master branch. |
fbfcdc75 |
168 | |
169 | It should be noted that if you want your specific branch to be approved, it is |
4c0880b2 |
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; |
fbfcdc75 |
172 | this allows us to better keep track of the branches awaiting approval and those |
173 | which have been approved. |
174 | |
175 | =over 4 |
176 | |
177 | =item Small bug fixes, doc patches and additional passing tests. |
178 | |
0b81ea16 |
179 | These items don't really require approval beyond one of the core contributors |
4c0880b2 |
180 | just doing a simple review. For especially simple patches (doc patches |
181 | especially), committing directly to master is fine. |
fbfcdc75 |
182 | |
183 | =item Larger bug fixes, doc additions and TODO or failing tests. |
184 | |
185 | Larger bug fixes should be reviewed by at least one cabal member and should be |
aefb302c |
186 | tested using the F<xt/author/test-my-dependents.t> test. |
fbfcdc75 |
187 | |
188 | New documentation is always welcome, but should also be reviewed by a cabal |
189 | member for accuracy. |
190 | |
0b81ea16 |
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 |
4c0880b2 |
193 | C<topic/> branch using the L</STANDARD WORKFLOW> and start hacking away. |
fbfcdc75 |
194 | |
0b81ea16 |
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. |
fbfcdc75 |
198 | |
199 | =item New user-facing features. |
200 | |
0b81ea16 |
201 | Anything that creates a new user-visible feature needs to be approved by |
eefea5b0 |
202 | B<more than one> cabal member. |
fbfcdc75 |
203 | |
0b81ea16 |
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. |
fbfcdc75 |
206 | |
207 | =item New internals features. |
208 | |
eefea5b0 |
209 | New features for Moose internals are less restrictive than user facing |
0b81ea16 |
210 | features, but still require approval by B<at least one> cabal member. |
fbfcdc75 |
211 | |
aefb302c |
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 |
215 | branch's approval. |
fbfcdc75 |
216 | |
217 | =item Backwards incompatible changes. |
218 | |
daae2c87 |
219 | Anything that breaks backwards compatibility must be discussed by the |
220 | cabal. Backwards incompatbible changes should not be merged to master if there |
221 | are strong objections for any cabal members. |
fbfcdc75 |
222 | |
0b81ea16 |
223 | We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for |
224 | Moose. If your changes break back-compat, you must be ready to discuss and |
225 | defend your change. |
fbfcdc75 |
226 | |
227 | =back |
228 | |
04437dba |
229 | =head1 RELEASE WORKFLOW |
230 | |
4c0880b2 |
231 | # major releases (including trial releases) |
04437dba |
232 | git checkout master |
4c0880b2 |
233 | |
234 | # minor releases |
235 | git checkout stable |
236 | |
04437dba |
237 | # edit for final version bumping, changelogging, etc |
238 | # prepare release (test suite etc) |
ba64b156 |
239 | perl-reversion -bump |
240 | make manifest |
04437dba |
241 | git commit |
4c0880b2 |
242 | git branch stable/2.XXYY # only for non-trial major releases |
3ba78ad9 |
243 | shipit # does not ship the tarball, but does everything else |
04437dba |
244 | |
4c0880b2 |
245 | # non-trial releases |
246 | cpan-upload ~/shipit-dist/Moose-2.XXYY.tar.gz |
247 | |
248 | # trial releases |
249 | cd ~/shipit-dist |
250 | mv Moose-2.XXYY.tar.gz Moose-2.XXYY-TRIAL.tar.gz |
251 | cpan-upload Moose-2.XXYY-TRIAL.tar.gz |
04437dba |
252 | |
6c1fa4ad |
253 | =head2 Release How-To |
254 | |
255 | Moose (and L<Class::MOP>) releases fall into two categories, each with their |
256 | own level of release preparation. A minor release is one which does not |
257 | include any API changes, deprecations, and so on. In that case, it is |
258 | sufficient to simply test the release candidate against a few different |
259 | different Perls. Testing should be done against at least two recent major |
260 | version of Perl (5.8.8 and 5.10.1, for example). If you have more versions |
261 | available, you are encouraged to test them all. However, we do not put a lot |
262 | of effort into supporting older 5.8.x releases. |
263 | |
264 | For major releases which include an API change or deprecation, you should run |
aefb302c |
265 | the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX |
266 | and other Moose-using modules from CPAN. In order to run this script, you must |
267 | arrange to have the new version of Moose and/or Class::MOP in Perl's include |
268 | path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle |
269 | with the C<PERL5LIB> environment variable, whatever makes you happy. |
270 | |
271 | This test downloads each module from CPAN, runs its tests, and logs failures |
272 | and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are |
6c1fa4ad |
273 | failures or warnings, please work with the authors of the modules in question |
274 | to fix them. If the module author simply isn't available or does not want to |
275 | fix the bug, it is okay to make a release. |
276 | |
277 | Regardless of whether or not a new module is available, any breakages should |
278 | be noted in the conflicts list in the distribution's F<Makefile.PL>. |
279 | |
280 | Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the |
281 | release goes smoothly. You are strongly encouraged to use this instead of |
282 | doing the final release steps by hand. |
283 | |
04437dba |
284 | =head1 EMERGENCY BUG WORKFLOW (for immediate release) |
285 | |
4c0880b2 |
286 | The stable branch exists for easily making bug fix releases. |
04437dba |
287 | |
288 | git remote update |
4c0880b2 |
289 | git checkout -b topic/my-emergency-fix origin/master |
04437dba |
290 | # hack |
291 | git commit |
292 | |
4c0880b2 |
293 | Then a cabal member merges into C<master>, and backports the change into |
294 | C<stable>: |
04437dba |
295 | |
4c0880b2 |
296 | git checkout master |
04437dba |
297 | git merge topic/my-emergency-fix |
298 | git push |
4c0880b2 |
299 | git checkout stable |
300 | git cherry-pick -x master |
301 | git push |
04437dba |
302 | # release |
04437dba |
303 | |
304 | =head1 PROJECT WORKFLOW |
305 | |
306 | For longer lasting branches, we use a subversion style branch layout, where |
307 | master is routinely merged into the branch. Rebasing is allowed as long as all |
5af926eb |
308 | the branch contributors are using C<git pull --rebase> properly. |
04437dba |
309 | |
310 | C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should |
311 | only be done in topic branches. Committing to master is still done with the |
312 | same review process as a topic branch, and the branch must merge as a fast |
313 | forward. |
314 | |
9840bb38 |
315 | This is pretty much the way we're doing branches for large-ish things right |
04437dba |
316 | now. |
317 | |
318 | Obviously there is no technical limitation on the number of branches. You can |
319 | freely create topic branches off of project branches, or sub projects inside |
320 | larger projects freely. Such branches should incorporate the name of the branch |
321 | they were made off so that people don't accidentally assume they should be |
322 | merged into master: |
323 | |
324 | git checkout -b my-project--topic/foo my-project |
325 | |
326 | (unfortunately Git will not allow C<my-project/foo> as a branch name if |
327 | C<my-project> is a valid ref). |
328 | |
04437dba |
329 | =head1 BRANCH ARCHIVAL |
330 | |
331 | Merged branches should be deleted. |
332 | |
daae2c87 |
333 | Failed branches may be kept, but should be moved to C<attic/> to differentiate |
334 | them from in-progress topic branches. |
04437dba |
335 | |
702e6744 |
336 | Branches that have not been worked on for a long time will be moved to |
4c0880b2 |
337 | C<abandoned/> periodically, but feel free to move the branch back to C<topic/> |
338 | if you want to start working on it again. |
04437dba |
339 | |
600f7f85 |
340 | =head1 TESTS, TESTS, TESTS |
341 | |
d85337ff |
342 | If you write I<any> code for Moose or Class::MOP, you B<must> add |
343 | tests for that code. If you do not write tests then we cannot |
04437dba |
344 | guarantee your change will not be removed or altered at a later date, |
345 | as there is nothing to confirm this is desired behavior. |
d85337ff |
346 | |
347 | If your code change/addition is deep within the bowels of |
348 | Moose/Class::MOP and your test exercises this feature in a non-obvious |
349 | way, please add some comments either near the code in question or in |
350 | the test so that others know. |
600f7f85 |
351 | |
4c0880b2 |
352 | We also greatly appreciate documentation to go with your changes, and an entry |
353 | in the Changes file. Make sure to give yourself credit! Major changes or new |
354 | user-facing features should also be documented in L<Moose::Manual::Delta>. |
600f7f85 |
355 | |
daae2c87 |
356 | =head1 DOCS, DOCS, DOCS |
357 | |
358 | Any user-facing changes must be accompanied by documentation. If you're not |
359 | comfortable writing docs yourself, you might be able to convince another Moose |
360 | dev to help you. |
361 | |
362 | Our goal is to make sure that all features are documented. Undocumented |
363 | features are not considered part of the API when it comes to determining |
364 | whether a change is backwards compatible. |
365 | |
d85337ff |
366 | =head1 BACKWARDS COMPATIBILITY |
600f7f85 |
367 | |
04437dba |
368 | Change is inevitable, and Moose is not immune to this. We do our best |
86b96832 |
369 | to maintain backwards compatibility, but we do not want the code base |
d85337ff |
370 | to become overburdened by this. This is not to say that we will be |
371 | frivolous with our changes, quite the opposite, just that we are not |
372 | afraid of change and will do our best to keep it as painless as |
373 | possible for the end user. |
600f7f85 |
374 | |
4c0880b2 |
375 | Our policy for handling backwards compatibility is documented in more detail in |
376 | L<Moose::Manual::Support>. |
600f7f85 |
377 | |
d85337ff |
378 | All backwards incompatible changes B<must> be documented in |
04437dba |
379 | L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds |
380 | for the change in that document. |
600f7f85 |
381 | |
382 | =head1 AUTHOR |
383 | |
384 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
385 | |
04437dba |
386 | Chris (perigrin) Prather |
387 | |
388 | Yuval (nothingmuch) Kogman |
389 | |
4c0880b2 |
390 | Jesse Luehrs E<lt>doy at tozt dot netE<gt> |
391 | |
600f7f85 |
392 | =head1 COPYRIGHT AND LICENSE |
393 | |
394 | Copyright 2009 by Infinity Interactive, Inc. |
395 | |
396 | L<http://www.iinteractive.com> |
397 | |
398 | This library is free software; you can redistribute it and/or modify |
399 | it under the same terms as Perl itself. |
400 | |
d85337ff |
401 | =cut |