1Moose::Manual::ContribuUtsienrg(C3o)ntributed Perl DocumMeonotsaet:i:oMnanual::Contributing(3)
2
6 Moose::Manual::Contributing - How to get involved in Moose
7
9 Moose is an open project, and we are always willing to accept bug
10 fixes, more tests, and documentation patches. Commit bits are given out
11 freely, and the "STANDARD WORKFLOW" is very simple. The general gist
12 is: clone the Git repository, create a new topic branch, hack away,
13 then find a committer to review your changes.
14 Note that this document applies to both Moose and Class::MOP
16 development.
17
19 Moose already has a fairly large feature set, and we are currently not
20 looking to add any major new features to it. If you have an idea for a
21 new feature in Moose, you are invited instead to create a MooseX module
22 first.
23 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 it
26 is absolutely 100% impossible to implement the feature outside the
27 core.
28 If you think it is 100% impossible, please come discuss it with us on
30 IRC or via e-mail. However, your feature may need a small hook in the
31 core, or a refactoring of some core modules, and we are definitely open
32 to that.
33 Moose was built from the ground up with the idea of being highly
35 extensible, and quite often the feature requests we see can be
36 implemented through a couple of small and well placed extensions. Try
37 it, it is much easier than you might think.
38
40 As Moose has matured, some structure has emerged in the process.
41 Contributors - people creating a topic or branch
43 You.
44 If you have commit access, you can create a topic on the main
46 Moose.git, otherwise either give us your SSH key or create your own
47 clone of the <git://git.moose.perl.org/Moose.git> repository or
48 fork of the GitHub mirror.
49 The relevant repository URIs are:
51 Read-Only
53 <git://git.moose.perl.org/Moose.git>
54 Read+Write
56 gitmo@git.moose.perl.org:Moose.git
57 Core Committers - people reviewing and merging a branch
59 These people have worked with the Moose codebase for a while.
60 They've been responsible for large features or branches and can
62 help review your changes and apply them to the master branch using
63 the basic "APPROVAL WORKFLOW".
64 They are also fairly well versed in Git, in order to merge the
66 branches with no mistakes (especially when the merge fails), and to
67 provide advice to contributors.
68 Cabal - people who can release moose
70 These people are the ones who have co-maint on Moose itself and can
71 create a release. They're listed under "CABAL" in Moose in the
72 Moose documentation. They merge from Master to Stable.
73
75 The repository is divided into several branches to make maintenance
76 easier for everyone involved. The branches below are ordered by level
77 of stability.
78 Stable (refs/heads/stable)
80 The branch from which releases are cut. When making a new release,
81 the release manager merges from master to stable. The stable branch
82 is only updated by someone from the Cabal during a release.
83 Master (refs/heads/master)
85 The branch for new development. This branch is merged into and
86 branched from.
87 Branches (refs/heads/*)
89 Large community branches for big development "projects".
90 Topics (refs/heads/topic/*)
92 Small personal branches that have been published for review, but
93 can get freely rebased. Targeted features that may span a handful
94 of commits.
95 Any change or bugfix should be created in a topic branch.
97
99 # update your copy of master
100 git checkout master
101 git pull --rebase
102 # create a new topic branch
104 git checkout -b topic/my-feature origin/master
105 # hack, commit, feel free to break fast forward
107 git commit --amend # allowed
108 git rebase --interactive # allowed
109 git push --force origin topic/my_feature # allowed
110 Then ask for a review/approval (see "APPROVAL WORKFLOW"), and merge to
112 master. If it merges cleanly and nobody has any objections, then it can
113 be pushed to master.
114 If it doesn't merge as a fast forward, the author of the branch needs
116 to run
117 git remote update
119 git rebase origin/master # or merge
120 and bring the branch up to date, so that it can be merged as a fast
122 forward into master.
123 No actual merging (as in a human resolving conflicts) should be done
125 when merging into master, only from master into other branches.
126 Preparing a topic branch
128 Before a merge, a topic branch can be cleaned up by the author.
129 This can be done using interactive rebase to combine commits, etc, or
131 even "git merge --squash" to make the whole topic into a single commit.
132 Structuring changes like this makes it easier to apply git revert at a
134 later date, and encourages a clean and descriptive history that
135 documents what the author was trying to do, without the various hangups
136 that happened while they were trying to do it (commits like "oops
137 forgot that file" are not only unnecessary noise, they also make
138 running things like git bisect or git revert harder).
139 However, by far the biggest benefit is that the number of commits that
141 go into master is eventually reduced, and they are simple and coherent,
142 making it much easier for people maintaining branches to stay up to
143 date.
144 All large changes should be documented in Moose::Manual::Delta.
146
148 Moose is an open project but it is also an increasingly important one.
149 Many modules depend on Moose being stable. Therefore, we have a basic
150 set of criteria for reviewing and merging branches. What follows is a
151 set of rough guidelines that ensures all new code is properly vetted
152 before it is merged to the master branch.
153 It should be noted that if you want your specific branch to be
155 approved, it is your responsibility to follow this process and advocate
156 for your branch. The preferred way is to send a request to the mailing
157 list for review/approval, this allows us to better keep track of the
158 branches awaiting approval and those which have been approved.
159 Small bug fixes, doc patches and additional passing tests.
161 These items don't really require approval beyond one of the core
162 contributors just doing a simple review.
163 Larger bug fixes, doc additions and TODO or failing tests.
165 Larger bug fixes should be reviewed by at least one cabal member
166 and should be tested using the xt/author/test-my-dependents.t test.
167 New documentation is always welcome, but should also be reviewed by
169 a cabal member for accuracy.
170 TODO tests are basically feature requests, see our "NEW FEATURES"
172 section for more information on that. If your feature needs core
173 support, create a topic/ branch using the "STANDARD WORKFLOW" and
174 start hacking away.
175 Failing tests are basically bug reports. You should find a core
177 contributor and/or cabal member to see if it is a real bug, then
178 submit the bug and your test to the RT queue. Source control is not
179 a bug reporting tool.
180 New user-facing features.
182 Anything that creates a new user-visible feature needs to be
183 approved by more than one cabal member.
184 Make sure you have reviewed "NEW FEATURES" to be sure that you are
186 following the guidelines. Do not be surprised if a new feature is
187 rejected for the core.
188 New internals features.
190 New features for Moose internals are less restrictive than user
191 facing features, but still require approval by at least one cabal
192 member.
193 Ideally you will have run the test-my-dependents.t script to be
195 sure you are not breaking any MooseX module or causing any other
196 unforeseen havoc. If you do this (rather than make us do it), it
197 will only help to hasten your branch's approval.
198 Backwards incompatible changes.
200 Anything that breaks backwards compatibility must be discussed by
201 the cabal and agreed to by a majority of the members.
202 We have a policy for what we see as sane "BACKWARDS COMPATIBILITY"
204 for Moose. If your changes break back-compat, you must be ready to
205 discuss and defend your change.
206
208 git checkout master
209 # edit for final version bumping, changelogging, etc
210 # prepare release (test suite etc)
211 perl-reversion -bump
212 make manifest
213 git commit
214 git checkout stable
215 git merge master # must be a fast forward
216 git push both
217 shipit # does not ship the tarball, but does everything else
218 cpan-upload ~/shipit-dist/Moose-X.YZ.tar.gz
219 Development releases are made without merging into the stable branch.
221 Release How-To
223 Moose (and Class::MOP) releases fall into two categories, each with
224 their own level of release preparation. A minor release is one which
225 does not include any API changes, deprecations, and so on. In that
226 case, it is sufficient to simply test the release candidate against a
227 few different different Perls. Testing should be done against at least
228 two recent major version of Perl (5.8.8 and 5.10.1, for example). If
229 you have more versions available, you are encouraged to test them all.
230 However, we do not put a lot of effort into supporting older 5.8.x
231 releases.
232 For major releases which include an API change or deprecation, you
234 should run the xt/author/test-my-dependents.t test. This tests a long
235 list of MooseX and other Moose-using modules from CPAN. In order to run
236 this script, you must arrange to have the new version of Moose and/or
237 Class::MOP in Perl's include path. You can use "prove -b" and "prove
238 -I", install the module, or fiddle with the "PERL5LIB" environment
239 variable, whatever makes you happy.
240 This test downloads each module from CPAN, runs its tests, and logs
242 failures and warnings to a set of files named test-mydeps-$$-*.log. If
243 there are failures or warnings, please work with the authors of the
244 modules in question to fix them. If the module author simply isn't
245 available or does not want to fix the bug, it is okay to make a
246 release.
247 Regardless of whether or not a new module is available, any breakages
249 should be noted in the conflicts list in the distribution's
250 Makefile.PL.
251 Both Class::MOP and Moose have a .shipit file you can use to make sure
253 the release goes smoothly. You are strongly encouraged to use this
254 instead of doing the final release steps by hand.
255
257 Anyone can create the necessary fix by branching off of the stable
258 branch:
259 git remote update
261 git checkout -b topic/my-emergency-fix origin/stable
262 # hack
263 git commit
264 Then a cabal member merges into stable:
266 git checkout stable
268 git merge topic/my-emergency-fix
269 git push
270 # release
271 git checkout master
272 git merge stable
273
275 For longer lasting branches, we use a subversion style branch layout,
276 where master is routinely merged into the branch. Rebasing is allowed
277 as long as all the branch contributors are using "git pull --rebase"
278 properly.
279 "commit --amend", "rebase --interactive", etc. are not allowed, and
281 should only be done in topic branches. Committing to master is still
282 done with the same review process as a topic branch, and the branch
283 must merge as a fast forward.
284 This is pretty much the way we're doing branches for large-ish things
286 right now.
287 Obviously there is no technical limitation on the number of branches.
289 You can freely create topic branches off of project branches, or sub
290 projects inside larger projects freely. Such branches should
291 incorporate the name of the branch they were made off so that people
292 don't accidentally assume they should be merged into master:
293 git checkout -b my-project--topic/foo my-project
295 (unfortunately Git will not allow "my-project/foo" as a branch name if
297 "my-project" is a valid ref).
298
300 To make things easier for longer lived branches (whether topics or
301 projects), the 'pu' branch is basically what happens if you merge all
302 of the branches and topics together with master.
303 We can update this as necessary (e.g. on a weekly basis if there is
305 merit), notifying the authors of the respective branches if their
306 branches did not merge (and why).
307 To update 'pu':
309 git checkout pu
311 git remote update
312 git reset --hard origin/master
313 git merge @all_the_branches
314 If the merge is clean, 'pu' is updated with "push --force".
316 If the merge is not clean, the offending branch is removed from
318 @all_the_branches, with a small note of the conflict, and we try again.
319 The authors of the failed branches should be told to try to merge their
321 branch into 'pu', to see how their branch interacts with other
322 branches.
323 'pu' is probably broken most of the time, but lets us know how the
325 different branches interact.
326
328 Merged branches should be deleted.
329 Failed branches may be kept, but consider moving to refs/attic/ (e.g.
331 http://danns.co.uk/node/295) to keep git branch -l current.
332 Any branch that could still realistically be merged in the future, even
334 if it hasn't had work recently, should not be archived.
335
337 If you write any code for Moose or Class::MOP, you must add tests for
338 that code. If you do not write tests then we cannot guarantee your
339 change will not be removed or altered at a later date, as there is
340 nothing to confirm this is desired behavior.
341 If your code change/addition is deep within the bowels of
343 Moose/Class::MOP and your test exercises this feature in a non-obvious
344 way, please add some comments either near the code in question or in
345 the test so that others know.
346 We also greatly appreciate documentation to go with your changes, and
348 an entry in the Changes file. Make sure to give yourself credit!
349
351 Change is inevitable, and Moose is not immune to this. We do our best
352 to maintain backwards compatibility, but we do not want the code base
353 to become overburdened by this. This is not to say that we will be
354 frivolous with our changes, quite the opposite, just that we are not
355 afraid of change and will do our best to keep it as painless as
356 possible for the end user.
357 The rule is that if you do something that is not backwards compatible,
359 you must do at least one deprecation cycle (more if it is larger
360 change). For really larger or radical changes dev releases may be
361 needed as well (the Cabal will decide on this on a case-per-case
362 basis).
363 Our policy with deprecation is that each deprecation should go through
365 several stages. First, we simply add a deprecation notice the
366 documentation in Changes and Moose::Manual::Delta. In a future release,
367 we then make the deprecated feature warn loudly and often so that users
368 will have time to fix their usages. Finally, the feature is removed in
369 a later release.
370 All backwards incompatible changes must be documented in
372 Moose::Manual::Delta. Make sure to document any useful tips or
373 workarounds for the change in that document.
374
376 Stevan Little <stevan@iinteractive.com>
377 Chris (perigrin) Prather
379 Yuval (nothingmuch) Kogman
381
383 Copyright 2009 by Infinity Interactive, Inc.
384 <http://www.iinteractive.com>
386 This library is free software; you can redistribute it and/or modify it
388 under the same terms as Perl itself.
389perl v5.12.2 2010-08-22 Moose::Manual::Contributing(3)