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 |
21 | idea for a new feature in Moose, you are invited instead 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. |
600f7f85 |
28 | |
04437dba |
29 | If you think it is 100% impossible, please come discuss it with us on IRC or |
30 | via e-mail. However, 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. |
d85337ff |
32 | |
33 | Moose was built from the ground up with the idea of being highly |
34 | extensible, and quite often the feature requests we see can be |
35 | implemented through a couple of small and well placed extensions. Try |
eefea5b0 |
36 | it, it is much easier than you might think. |
600f7f85 |
37 | |
04437dba |
38 | =head1 PEOPLE |
39 | |
40 | As Moose has matured, some structure has emerged in the process. |
41 | |
42 | =over |
43 | |
44 | =item Contributors - people creating a topic or branch |
45 | |
46 | You. |
47 | |
48 | If you have commit access, you can create a topic on the main Moose.git, |
49 | otherwise either give us your SSH key or create your own clone of the |
5af926eb |
50 | L<git://git.moose.perl.org/Moose.git> repository or fork of the GitHub mirror. |
04437dba |
51 | |
76127c77 |
52 | The relevant repository URIs are: |
53 | |
54 | =over |
55 | |
56 | =item Read-Only |
57 | |
58 | L<git://git.moose.perl.org/Moose.git> |
59 | |
60 | =item Read+Write |
61 | |
62 | L<gitmo@git.moose.perl.org:Moose.git> |
63 | |
64 | =back |
65 | |
04437dba |
66 | =item Core Committers - people reviewing and merging a branch |
67 | |
68 | These people have worked with the Moose codebase for a while. |
69 | |
70 | They've been responsible for large features or branches and can help review |
fbfcdc75 |
71 | your changes and apply them to the master branch using the basic |
72 | L</APPROVAL WORKFLOW>. |
04437dba |
73 | |
74 | They are also fairly well versed in Git, in order to merge the branches with |
75 | no mistakes (especially when the merge fails), and to provide advice to |
76 | contributors. |
77 | |
78 | =item Cabal - people who can release moose |
79 | |
80 | These people are the ones who have co-maint on Moose itself and can create a |
81 | release. They're listed under L<Moose/CABAL> in the Moose documentation. They |
82 | merge from Master to Stable. |
83 | |
84 | =back |
85 | |
86 | =head1 BRANCH LAYOUT |
87 | |
5af926eb |
88 | The repository is divided into several branches to make maintenance easier for |
04437dba |
89 | everyone involved. The branches below are ordered by level of stability. |
90 | |
91 | =over |
92 | |
93 | =item Stable (refs/heads/stable) |
94 | |
95 | The branch from which releases are cut. When making a new release, the |
96 | release manager merges from master to stable. The stable branch is only |
97 | updated by someone from the Cabal during a release. |
98 | |
99 | =item Master (refs/heads/master) |
100 | |
101 | The branch for new development. This branch is merged into and branched from. |
102 | |
103 | =item Branches (refs/heads/*) |
104 | |
105 | Large community branches for big development "projects". |
106 | |
6106b7a2 |
107 | =item Topics (refs/heads/topic/*) |
04437dba |
108 | |
109 | Small personal branches that have been published for review, but can get |
9840bb38 |
110 | freely rebased. Targeted features that may span a handful of commits. |
04437dba |
111 | |
112 | Any change or bugfix should be created in a topic branch. |
113 | |
114 | =back |
115 | |
116 | =head1 STANDARD WORKFLOW |
117 | |
118 | # update your copy of master |
119 | git checkout master |
120 | git pull --rebase |
121 | |
122 | # create a new topic branch |
123 | git checkout -b topic/my-feature |
124 | |
125 | # hack, commit, feel free to break fast forward |
126 | git commit --amend # allowed |
127 | git rebase --interactive # allowed |
128 | git push --force origin topic/my_feature # allowed |
129 | |
fbfcdc75 |
130 | Then ask for a review/approval (see L</APPROVAL WORKFLOW>), and merge |
131 | to master. If it merges cleanly and nobody has any objections, then it |
132 | can be pushed to master. |
04437dba |
133 | |
134 | If it doesn't merge as a fast forward, the author of the branch needs to run |
135 | |
136 | git remote update |
137 | git rebase origin/master # or merge |
138 | |
139 | and bring the branch up to date, so that it can be merged as a fast forward |
140 | into master. |
141 | |
142 | No actual merging (as in a human resolving conflicts) should be done when |
143 | merging into master, only from master into other branches. |
144 | |
145 | =head2 Preparing a topic branch |
146 | |
147 | Before a merge, a topic branch can be cleaned up by the author. |
148 | |
149 | This can be done using interactive rebase to combine commits, etc, or even |
150 | C<git merge --squash> to make the whole topic into a single commit. |
151 | |
152 | Structuring changes like this makes it easier to apply git revert at a later |
153 | date, and encourages a clean and descriptive history that documents what the |
154 | author was trying to do, without the various hangups that happened while they |
155 | were trying to do it (commits like "oops forgot that file" are not only |
156 | unnecessary noise, they also make running things like git bisect or git revert |
157 | harder). |
158 | |
159 | However, by far the biggest benefit is that the number of commits that go into |
160 | master is eventually reduced, and they are simple and coherent, making it much |
161 | easier for people maintaining branches to stay up to date. |
162 | |
163 | All large changes should be documented in L<Moose::Manual::Delta>. |
164 | |
fbfcdc75 |
165 | =head1 APPROVAL WORKFLOW |
166 | |
0b81ea16 |
167 | Moose is an open project but it is also an increasingly important one. Many |
168 | modules depend on Moose being stable. Therefore, we have a basic set of |
169 | criteria for reviewing and merging branches. What follows is a set of rough |
170 | guidelines that ensures all new code is properly vetted before it is merged to |
171 | the master branch. |
fbfcdc75 |
172 | |
173 | It should be noted that if you want your specific branch to be approved, it is |
174 | B<your> responsibility to follow this process and advocate for your branch. |
175 | The preferred way is to send a request to the mailing list for review/approval, |
176 | this allows us to better keep track of the branches awaiting approval and those |
177 | which have been approved. |
178 | |
179 | =over 4 |
180 | |
181 | =item Small bug fixes, doc patches and additional passing tests. |
182 | |
0b81ea16 |
183 | These items don't really require approval beyond one of the core contributors |
184 | just doing a simple review. |
fbfcdc75 |
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 |
aefb302c |
189 | tested using the F<xt/author/test-my-dependents.t> test. |
fbfcdc75 |
190 | |
191 | New documentation is always welcome, but should also be reviewed by a cabal |
192 | member for accuracy. |
193 | |
0b81ea16 |
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 | topic/ branch using the L</STANDARD WORKFLOW> and start hacking away. |
fbfcdc75 |
197 | |
0b81ea16 |
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. |
fbfcdc75 |
201 | |
202 | =item New user-facing features. |
203 | |
0b81ea16 |
204 | Anything that creates a new user-visible feature needs to be approved by |
eefea5b0 |
205 | B<more than one> cabal member. |
fbfcdc75 |
206 | |
0b81ea16 |
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. |
fbfcdc75 |
209 | |
210 | =item New internals features. |
211 | |
eefea5b0 |
212 | New features for Moose internals are less restrictive than user facing |
0b81ea16 |
213 | features, but still require approval by B<at least one> cabal member. |
fbfcdc75 |
214 | |
aefb302c |
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. |
fbfcdc75 |
219 | |
220 | =item Backwards incompatible changes. |
221 | |
0b81ea16 |
222 | Anything that breaks backwards compatibility must be discussed by the cabal |
223 | and agreed to by a majority of the members. |
fbfcdc75 |
224 | |
0b81ea16 |
225 | We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for |
226 | Moose. If your changes break back-compat, you must be ready to discuss and |
227 | defend your change. |
fbfcdc75 |
228 | |
229 | =back |
230 | |
04437dba |
231 | =head1 RELEASE WORKFLOW |
232 | |
233 | git checkout master |
234 | # edit for final version bumping, changelogging, etc |
235 | # prepare release (test suite etc) |
236 | git commit |
237 | git checkout stable |
238 | git merge master # must be a fast forward |
239 | git push both |
3ba78ad9 |
240 | shipit # does not ship the tarball, but does everything else |
241 | cpan-upload ~/shipit-dist/Moose-X.YZ.tar.gz |
04437dba |
242 | |
243 | Development releases are made without merging into the stable branch. |
244 | |
6c1fa4ad |
245 | =head2 Release How-To |
246 | |
247 | Moose (and L<Class::MOP>) releases fall into two categories, each with their |
248 | own level of release preparation. A minor release is one which does not |
249 | include any API changes, deprecations, and so on. In that case, it is |
250 | sufficient to simply test the release candidate against a few different |
251 | different Perls. Testing should be done against at least two recent major |
252 | version of Perl (5.8.8 and 5.10.1, for example). If you have more versions |
253 | available, you are encouraged to test them all. However, we do not put a lot |
254 | of effort into supporting older 5.8.x releases. |
255 | |
256 | For major releases which include an API change or deprecation, you should run |
aefb302c |
257 | the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX |
258 | and other Moose-using modules from CPAN. In order to run this script, you must |
259 | arrange to have the new version of Moose and/or Class::MOP in Perl's include |
260 | path. You can use C<prove -b> and C<prove -I>, install the module, or fiddle |
261 | with the C<PERL5LIB> environment variable, whatever makes you happy. |
262 | |
263 | This test downloads each module from CPAN, runs its tests, and logs failures |
264 | and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are |
6c1fa4ad |
265 | failures or warnings, please work with the authors of the modules in question |
266 | to fix them. If the module author simply isn't available or does not want to |
267 | fix the bug, it is okay to make a release. |
268 | |
269 | Regardless of whether or not a new module is available, any breakages should |
270 | be noted in the conflicts list in the distribution's F<Makefile.PL>. |
271 | |
272 | Both Class::MOP and Moose have a F<.shipit> file you can use to make sure the |
273 | release goes smoothly. You are strongly encouraged to use this instead of |
274 | doing the final release steps by hand. |
275 | |
04437dba |
276 | =head1 EMERGENCY BUG WORKFLOW (for immediate release) |
277 | |
278 | Anyone can create the necessary fix by branching off of the stable branch: |
279 | |
280 | git remote update |
fd9e0bac |
281 | git checkout -b topic/my-emergency-fix origin/stable |
04437dba |
282 | # hack |
283 | git commit |
284 | |
285 | Then a cabal member merges into stable: |
286 | |
287 | git checkout stable |
288 | git merge topic/my-emergency-fix |
289 | git push |
290 | # release |
291 | git checkout master |
292 | git merge stable |
293 | |
294 | =head1 PROJECT WORKFLOW |
295 | |
296 | For longer lasting branches, we use a subversion style branch layout, where |
297 | master is routinely merged into the branch. Rebasing is allowed as long as all |
5af926eb |
298 | the branch contributors are using C<git pull --rebase> properly. |
04437dba |
299 | |
300 | C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should |
301 | only be done in topic branches. Committing to master is still done with the |
302 | same review process as a topic branch, and the branch must merge as a fast |
303 | forward. |
304 | |
9840bb38 |
305 | This is pretty much the way we're doing branches for large-ish things right |
04437dba |
306 | now. |
307 | |
308 | Obviously there is no technical limitation on the number of branches. You can |
309 | freely create topic branches off of project branches, or sub projects inside |
310 | larger projects freely. Such branches should incorporate the name of the branch |
311 | they were made off so that people don't accidentally assume they should be |
312 | merged into master: |
313 | |
314 | git checkout -b my-project--topic/foo my-project |
315 | |
316 | (unfortunately Git will not allow C<my-project/foo> as a branch name if |
317 | C<my-project> is a valid ref). |
318 | |
319 | =head1 THE "PU" BRANCH |
320 | |
321 | To make things easier for longer lived branches (whether topics or projects), |
322 | the 'pu' branch is basically what happens if you merge all of the branches and |
323 | topics together with master. |
324 | |
325 | We can update this as necessary (e.g. on a weekly basis if there is merit), |
326 | notifying the authors of the respective branches if their branches did not merge |
327 | (and why). |
328 | |
329 | To update 'pu': |
330 | |
331 | git checkout pu |
332 | git remote update |
333 | git reset --hard origin/master |
334 | git merge @all_the_branches |
335 | |
336 | If the merge is clean, 'pu' is updated with C<push --force>. |
337 | |
338 | If the merge is not clean, the offending branch is removed from |
339 | C<@all_the_branches>, with a small note of the conflict, and we try again. |
340 | |
341 | The authors of the failed branches should be told to try to merge their branch |
342 | into 'pu', to see how their branch interacts with other branches. |
343 | |
344 | 'pu' is probably broken most of the time, but lets us know how the different |
345 | branches interact. |
346 | |
347 | =head1 BRANCH ARCHIVAL |
348 | |
349 | Merged branches should be deleted. |
350 | |
351 | Failed branches may be kept, but consider moving to refs/attic/ (e.g. |
352 | http://danns.co.uk/node/295) to keep git branch -l current. |
353 | |
354 | Any branch that could still realistically be merged in the future, even if it |
355 | hasn't had work recently, should not be archived. |
356 | |
600f7f85 |
357 | =head1 TESTS, TESTS, TESTS |
358 | |
d85337ff |
359 | If you write I<any> code for Moose or Class::MOP, you B<must> add |
360 | tests for that code. If you do not write tests then we cannot |
04437dba |
361 | guarantee your change will not be removed or altered at a later date, |
362 | as there is nothing to confirm this is desired behavior. |
d85337ff |
363 | |
364 | If your code change/addition is deep within the bowels of |
365 | Moose/Class::MOP and your test exercises this feature in a non-obvious |
366 | way, please add some comments either near the code in question or in |
367 | the test so that others know. |
600f7f85 |
368 | |
d85337ff |
369 | We also greatly appreciate documentation to go with your changes, and |
370 | an entry in the Changes file. Make sure to give yourself credit! |
600f7f85 |
371 | |
d85337ff |
372 | =head1 BACKWARDS COMPATIBILITY |
600f7f85 |
373 | |
04437dba |
374 | Change is inevitable, and Moose is not immune to this. We do our best |
86b96832 |
375 | to maintain backwards compatibility, but we do not want the code base |
d85337ff |
376 | to become overburdened by this. This is not to say that we will be |
377 | frivolous with our changes, quite the opposite, just that we are not |
378 | afraid of change and will do our best to keep it as painless as |
379 | possible for the end user. |
600f7f85 |
380 | |
04437dba |
381 | The rule is that if you do something that is not backwards compatible, you |
382 | B<must> do I<at least> one deprecation cycle (more if it is larger change). |
383 | For really larger or radical changes dev releases may be needed as well (the |
384 | Cabal will decide on this on a case-per-case basis). |
600f7f85 |
385 | |
9f41127c |
386 | Our policy with deprecation is that each deprecation should go through several |
387 | stages. First, we simply add a deprecation notice the documentation in |
388 | F<Changes> and L<Moose::Manual::Delta>. In a future release, we then make the |
389 | deprecated feature warn loudly and often so that users will have time to fix |
390 | their usages. Finally, the feature is removed in a later release. |
600f7f85 |
391 | |
d85337ff |
392 | All backwards incompatible changes B<must> be documented in |
04437dba |
393 | L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds |
394 | for the change in that document. |
600f7f85 |
395 | |
396 | =head1 AUTHOR |
397 | |
398 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
399 | |
04437dba |
400 | Chris (perigrin) Prather |
401 | |
402 | Yuval (nothingmuch) Kogman |
403 | |
600f7f85 |
404 | =head1 COPYRIGHT AND LICENSE |
405 | |
406 | Copyright 2009 by Infinity Interactive, Inc. |
407 | |
408 | L<http://www.iinteractive.com> |
409 | |
410 | This library is free software; you can redistribute it and/or modify |
411 | it under the same terms as Perl itself. |
412 | |
d85337ff |
413 | =cut |