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