5 Moose::Manual::Contributing - How to get involved in Moose
7 =head1 GETTING INVOLVED
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
17 Moose already has a fairly large feature set, and we are currently
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
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
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.
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.
38 As Moose has matured, some structure has emerged in the process.
42 =item Contributors - people creating a topic or branch
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
48 L<git://git.moose.perl.org/Moose.git> repository or fork of the GitHub mirror.
50 =item Core Committers - people reviewing and merging a branch
52 These people have worked with the Moose codebase for a while.
54 They've been responsible for large features or branches and can help review
55 your changes and apply them to the master branch.
57 They are also fairly well versed in Git, in order to merge the branches with
58 no mistakes (especially when the merge fails), and to provide advice to
61 =item Cabal - people who can release moose
63 These people are the ones who have co-maint on Moose itself and can create a
64 release. They're listed under L<Moose/CABAL> in the Moose documentation. They
65 merge from Master to Stable.
71 The repository is divided into several branches to make maintenance easier for
72 everyone involved. The branches below are ordered by level of stability.
76 =item Stable (refs/heads/stable)
78 The branch from which releases are cut. When making a new release, the
79 release manager merges from master to stable. The stable branch is only
80 updated by someone from the Cabal during a release.
82 =item Master (refs/heads/master)
84 The branch for new development. This branch is merged into and branched from.
86 =item Branches (refs/heads/*)
88 Large community branches for big development "projects".
90 =item Topics (refs/heads/topic/*)
92 Small personal branches that have been published for review, but can get
93 freely rebased. Targeted features that may span a handful of commits.
95 Any change or bugfix should be created in a topic branch.
99 =head1 STANDARD WORKFLOW
101 # update your copy of master
105 # create a new topic branch
106 git checkout -b topic/my-feature
108 # hack, commit, feel free to break fast forward
109 git commit --amend # allowed
110 git rebase --interactive # allowed
111 git push --force origin topic/my_feature # allowed
113 Then go on IRC, ask for someone to review, and merge to master. If it merges
114 cleanly and nobody has any objections, then it can be pushed to master.
116 If it doesn't merge as a fast forward, the author of the branch needs to run
119 git rebase origin/master # or merge
121 and bring the branch up to date, so that it can be merged as a fast forward
124 No actual merging (as in a human resolving conflicts) should be done when
125 merging into master, only from master into other branches.
127 =head2 Preparing a topic branch
129 Before a merge, a topic branch can be cleaned up by the author.
131 This can be done using interactive rebase to combine commits, etc, or even
132 C<git merge --squash> to make the whole topic into a single commit.
134 Structuring changes like this makes it easier to apply git revert at a later
135 date, and encourages a clean and descriptive history that documents what the
136 author was trying to do, without the various hangups that happened while they
137 were trying to do it (commits like "oops forgot that file" are not only
138 unnecessary noise, they also make running things like git bisect or git revert
141 However, by far the biggest benefit is that the number of commits that go into
142 master is eventually reduced, and they are simple and coherent, making it much
143 easier for people maintaining branches to stay up to date.
145 All large changes should be documented in L<Moose::Manual::Delta>.
147 =head1 RELEASE WORKFLOW
150 # edit for final version bumping, changelogging, etc
151 # prepare release (test suite etc)
154 git merge master # must be a fast forward
158 Development releases are made without merging into the stable branch.
160 =head1 EMERGENCY BUG WORKFLOW (for immediate release)
162 Anyone can create the necessary fix by branching off of the stable branch:
165 git checkout -b topic/my-emergency-fix origin/stable
169 Then a cabal member merges into stable:
172 git merge topic/my-emergency-fix
178 =head1 PROJECT WORKFLOW
180 For longer lasting branches, we use a subversion style branch layout, where
181 master is routinely merged into the branch. Rebasing is allowed as long as all
182 the branch contributors are using C<git pull --rebase> properly.
184 C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
185 only be done in topic branches. Committing to master is still done with the
186 same review process as a topic branch, and the branch must merge as a fast
189 This is pretty much the way we're doing branches for large-ish things right
192 Obviously there is no technical limitation on the number of branches. You can
193 freely create topic branches off of project branches, or sub projects inside
194 larger projects freely. Such branches should incorporate the name of the branch
195 they were made off so that people don't accidentally assume they should be
198 git checkout -b my-project--topic/foo my-project
200 (unfortunately Git will not allow C<my-project/foo> as a branch name if
201 C<my-project> is a valid ref).
203 =head1 THE "PU" BRANCH
205 To make things easier for longer lived branches (whether topics or projects),
206 the 'pu' branch is basically what happens if you merge all of the branches and
207 topics together with master.
209 We can update this as necessary (e.g. on a weekly basis if there is merit),
210 notifying the authors of the respective branches if their branches did not merge
217 git reset --hard origin/master
218 git merge @all_the_branches
220 If the merge is clean, 'pu' is updated with C<push --force>.
222 If the merge is not clean, the offending branch is removed from
223 C<@all_the_branches>, with a small note of the conflict, and we try again.
225 The authors of the failed branches should be told to try to merge their branch
226 into 'pu', to see how their branch interacts with other branches.
228 'pu' is probably broken most of the time, but lets us know how the different
231 =head1 BRANCH ARCHIVAL
233 Merged branches should be deleted.
235 Failed branches may be kept, but consider moving to refs/attic/ (e.g.
236 http://danns.co.uk/node/295) to keep git branch -l current.
238 Any branch that could still realistically be merged in the future, even if it
239 hasn't had work recently, should not be archived.
241 =head1 TESTS, TESTS, TESTS
243 If you write I<any> code for Moose or Class::MOP, you B<must> add
244 tests for that code. If you do not write tests then we cannot
245 guarantee your change will not be removed or altered at a later date,
246 as there is nothing to confirm this is desired behavior.
248 If your code change/addition is deep within the bowels of
249 Moose/Class::MOP and your test exercises this feature in a non-obvious
250 way, please add some comments either near the code in question or in
251 the test so that others know.
253 We also greatly appreciate documentation to go with your changes, and
254 an entry in the Changes file. Make sure to give yourself credit!
256 =head1 BACKWARDS COMPATIBILITY
258 Change is inevitable, and Moose is not immune to this. We do our best
259 to maintain backwards compatibility, but we do not want the code base
260 to become overburdened by this. This is not to say that we will be
261 frivolous with our changes, quite the opposite, just that we are not
262 afraid of change and will do our best to keep it as painless as
263 possible for the end user.
265 The rule is that if you do something that is not backwards compatible, you
266 B<must> do I<at least> one deprecation cycle (more if it is larger change).
267 For really larger or radical changes dev releases may be needed as well (the
268 Cabal will decide on this on a case-per-case basis).
270 The preference with regard to deprecation is to warn loudly and often so that
271 users will have time to fix their usages.
273 All backwards incompatible changes B<must> be documented in
274 L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
275 for the change in that document.
279 Stevan Little E<lt>stevan@iinteractive.comE<gt>
281 Chris (perigrin) Prather
283 Yuval (nothingmuch) Kogman
285 =head1 COPYRIGHT AND LICENSE
287 Copyright 2009 by Infinity Interactive, Inc.
289 L<http://www.iinteractive.com>
291 This library is free software; you can redistribute it and/or modify
292 it under the same terms as Perl itself.