close over the coercion sub separately
[gitmo/Moose.git] / lib / Moose / Manual / Contributing.pod
CommitLineData
daa0fd7d 1package Moose::Manual::Contributing;
2
3# ABSTRACT: How to get involved in Moose
600f7f85 4
daa0fd7d 5__END__
600f7f85 6
daa0fd7d 7=pod
600f7f85 8
9=head1 GETTING INVOLVED
10
04437dba 11Moose is an open project, and we are always willing to accept bug fixes,
12more tests, and documentation patches. Commit bits are given out freely, and
13the L</STANDARD WORKFLOW> is very simple. The general gist is: clone the Git
14repository, create a new topic branch, hack away, then find a committer to
15review your changes.
600f7f85 16
17=head1 NEW FEATURES
18
04437dba 19Moose already has a fairly large feature set, and we are currently
d85337ff 20B<not> looking to add any major new features to it. If you have an
482cc243 21idea for a new feature in Moose, you are encouraged to create a
d85337ff 22MooseX module first.
23
24At this stage, no new features will even be considered for addition
25into the core without first being vetted as a MooseX module, unless
26it is absolutely 100% impossible to implement the feature outside the
27core.
600f7f85 28
04437dba 29If you think it is 100% impossible, please come discuss it with us on IRC or
482cc243 30via e-mail. Your feature may need a small hook in the core, or a
04437dba 31refactoring of some core modules, and we are definitely open to that.
d85337ff 32
482cc243 33Moose was built from the ground up with the idea of being highly extensible,
34and quite often the feature requests we see can be implemented through small
35extensions. Try it, it's much easier than you might think.
600f7f85 36
04437dba 37=head1 PEOPLE
38
39As Moose has matured, some structure has emerged in the process.
40
41=over
42
43=item Contributors - people creating a topic or branch
44
45You.
46
37a2fef8 47If you have commit access, you can create a topic on the main Moose.git
48repository. If you don't have a commit bit, give us your SSH key or create your
49own clone of the L<git://git.moose.perl.org/Moose.git> repository.
04437dba 50
76127c77 51The relevant repository URIs are:
52
53=over
54
55=item Read-Only
56
57L<git://git.moose.perl.org/Moose.git>
58
59=item Read+Write
60
61L<gitmo@git.moose.perl.org:Moose.git>
62
63=back
64
04437dba 65=item Cabal - people who can release moose
66
67These people are the ones who have co-maint on Moose itself and can create a
68release. They're listed under L<Moose/CABAL> in the Moose documentation. They
4c0880b2 69are responsible for reviewing branches, and are the only people who are allowed
70to push to stable branches.
04437dba 71
794c5045 72Cabal members are listed in L<Moose> and can often be found on irc in the
73L<irc://irc.perl.org/#moose-dev> channel.
74
04437dba 75=back
76
77=head1 BRANCH LAYOUT
78
5af926eb 79The repository is divided into several branches to make maintenance easier for
04437dba 80everyone involved. The branches below are ordered by level of stability.
81
82=over
83
4c0880b2 84=item stable/*
85
86The branch from which releases are cut. When making a new major release, the
c5d6da29 87release manager makes a new C<stable/X.YY> branch at the current position of
88C<master>. The version used in the stable branch should not include the last
89two digits of the version number.
90
91For minor releases, patches will be committed to C<master>, and
92backported (cherry-picked) to the appropriate stable branch as needed. A
93stable branch is only updated by someone from the Cabal during a release.
04437dba 94
4c0880b2 95=item master
04437dba 96
4c0880b2 97The main development branch. All new code should be written against this
98branch. This branch contains code that has been reviewed, and will be included
99in the next major release. Commits which are judged to not break backwards
100compatibility may be backported into C<stable> to be included in the next minor
101release.
04437dba 102
4c0880b2 103=item rfc/*
04437dba 104
4c0880b2 105Topic branches that are completed and waiting on review. A Cabal member will
106look over branches in this namespace, and either merge them to C<master> if
107they are acceptable, or move them back to a different namespace otherwise.
04437dba 108
4c0880b2 109=item topic/*
04437dba 110
4c0880b2 111Small personal branches that are still in progress. They can be freely rebased.
112They contain targeted features that may span a handful of commits. Any change
113or bugfix should be created in a topic branch.
04437dba 114
4c0880b2 115=item attic/*
04437dba 116
4c0880b2 117Branches which have been reviewed, and rejected. They remain in the repository
118in case we later change our mind, or in case parts of them are still useful.
119
120=item abandoned/*
121
122Topic branches which have had no activity for a long period of time will be
123moved here, to keep the main areas clean.
04437dba 124
125=back
126
daae2c87 127Larger, longer term branches can also be created in the root namespace (i.e.
128at the same level as master and stable). This may be appropriate if multiple
4c0880b2 129people are intending to work on the branch. These branches should not be
daae2c87 130rebased without checking with other developers first.
4c0880b2 131
04437dba 132=head1 STANDARD WORKFLOW
133
134 # update your copy of master
135 git checkout master
136 git pull --rebase
137
138 # create a new topic branch
4c0880b2 139 git checkout -b topic/my-feature
04437dba 140
141 # hack, commit, feel free to break fast forward
4c0880b2 142 git commit --amend # allowed
143 git rebase --interactive # allowed
144 git push --force # allowed
04437dba 145
4c0880b2 146 # keep the branch rebased on top of master, for easy reviewing
04437dba 147 git remote update
4c0880b2 148 git rebase origin/master
149 git push --force
04437dba 150
4c0880b2 151 # when finished, move the branch to the rfc/ namespace
152 git branch -m rfc/my-feature
153 git push
154 git push origin :topic/my-feature
04437dba 155
4c0880b2 156When your branch is completed, make sure it has been moved to the C<rfc/>
157namespace and is rebased on top of master, and ask for review/approval (see
158L</APPROVAL WORKFLOW>). If it is approved, the reviewer will merge it into
159C<master>.
04437dba 160
4c0880b2 161No actual merging (as in a human resolving conflicts) should be done when
162merging into C<master>, only from C<master> into other branches.
04437dba 163
fbfcdc75 164=head1 APPROVAL WORKFLOW
165
0b81ea16 166Moose is an open project but it is also an increasingly important one. Many
167modules depend on Moose being stable. Therefore, we have a basic set of
168criteria for reviewing and merging branches. What follows is a set of rough
169guidelines that ensures all new code is properly vetted before it is merged to
170the master branch.
fbfcdc75 171
172It should be noted that if you want your specific branch to be approved, it is
4c0880b2 173B<your> responsibility to follow this process and advocate for your branch. The
174preferred way is to send a request to the mailing list for review/approval;
fbfcdc75 175this allows us to better keep track of the branches awaiting approval and those
176which have been approved.
177
178=over 4
179
180=item Small bug fixes, doc patches and additional passing tests.
181
0b81ea16 182These items don't really require approval beyond one of the core contributors
4c0880b2 183just doing a simple review. For especially simple patches (doc patches
184especially), committing directly to master is fine.
fbfcdc75 185
186=item Larger bug fixes, doc additions and TODO or failing tests.
187
188Larger bug fixes should be reviewed by at least one cabal member and should be
aefb302c 189tested using the F<xt/author/test-my-dependents.t> test.
fbfcdc75 190
191New documentation is always welcome, but should also be reviewed by a cabal
192member for accuracy.
193
0b81ea16 194TODO tests are basically feature requests, see our L</NEW FEATURES> section
195for more information on that. If your feature needs core support, create a
4c0880b2 196C<topic/> branch using the L</STANDARD WORKFLOW> and start hacking away.
fbfcdc75 197
0b81ea16 198Failing tests are basically bug reports. You should find a core contributor
199and/or cabal member to see if it is a real bug, then submit the bug and your
200test to the RT queue. Source control is not a bug reporting tool.
fbfcdc75 201
202=item New user-facing features.
203
0b81ea16 204Anything that creates a new user-visible feature needs to be approved by
eefea5b0 205B<more than one> cabal member.
fbfcdc75 206
0b81ea16 207Make sure you have reviewed L</NEW FEATURES> to be sure that you are following
208the guidelines. Do not be surprised if a new feature is rejected for the core.
fbfcdc75 209
210=item New internals features.
211
eefea5b0 212New features for Moose internals are less restrictive than user facing
0b81ea16 213features, but still require approval by B<at least one> cabal member.
fbfcdc75 214
aefb302c 215Ideally you will have run the F<test-my-dependents.t> script to be sure you
216are not breaking any MooseX module or causing any other unforeseen havoc. If
217you do this (rather than make us do it), it will only help to hasten your
218branch's approval.
fbfcdc75 219
220=item Backwards incompatible changes.
221
daae2c87 222Anything that breaks backwards compatibility must be discussed by the
789c6c1f 223cabal. Backwards incompatible changes should not be merged to master if there
515d5e41 224are strong objections from any cabal members.
fbfcdc75 225
0b81ea16 226We have a policy for what we see as sane L</BACKWARDS COMPATIBILITY> for
227Moose. If your changes break back-compat, you must be ready to discuss and
228defend your change.
fbfcdc75 229
230=back
231
04437dba 232=head1 RELEASE WORKFLOW
233
4c0880b2 234 # major releases (including trial releases)
04437dba 235 git checkout master
4c0880b2 236
237 # minor releases
c5d6da29 238 git checkout stable/X.YY
4c0880b2 239
aa2c2825 240 # do final changelogging, etc
241 vim dist.ini # increment version number
04437dba 242 git commit
aa2c2825 243 dzil release # or dzil release --trial for trial releases
244 git commit # to add the actual release date
c5d6da29 245 git branch stable/X.YY # only for non-trial major releases
04437dba 246
6c1fa4ad 247=head2 Release How-To
248
aa2c2825 249Moose uses L<Dist::Zilla> to manage releases. Although the git repository comes
250with a C<Makefile.PL>, it is a very basic one just to allow the basic
251C<perl Makefile.PL && make && make test> cycle to work. In particular, it
252doesn't include any release metadata, such as dependencies. In order to get
253started with Dist::Zilla, first install it: C<cpanm Dist::Zilla>, and then
254install the plugins necessary for reading the C<dist.ini>:
255C<dzil authordeps | cpanm>.
256
257Moose releases fall into two categories, each with their own level of release
258preparation. A minor release is one which does not include any API changes,
259deprecations, and so on. In that case, it is sufficient to simply test the
260release candidate against a few different different Perls. Testing should be
261done against at least two recent major version of Perl (5.8.8 and 5.10.1, for
262example). If you have more versions available, you are encouraged to test them
263all. However, we do not put a lot of effort into supporting older 5.8.x
264releases.
6c1fa4ad 265
266For major releases which include an API change or deprecation, you should run
aefb302c 267the F<xt/author/test-my-dependents.t> test. This tests a long list of MooseX
268and other Moose-using modules from CPAN. In order to run this script, you must
aa2c2825 269arrange to have the new version of Moose in Perl's include path. You can use
270C<prove -b> and C<prove -I>, install the module, or fiddle with the C<PERL5LIB>
271environment variable, whatever makes you happy.
aefb302c 272
273This test downloads each module from CPAN, runs its tests, and logs failures
274and warnings to a set of files named F<test-mydeps-$$-*.log>. If there are
6c1fa4ad 275failures or warnings, please work with the authors of the modules in question
276to fix them. If the module author simply isn't available or does not want to
277fix the bug, it is okay to make a release.
278
279Regardless of whether or not a new module is available, any breakages should
81156460 280be noted in the conflicts list in the distribution's F<dist.ini>.
6c1fa4ad 281
04437dba 282=head1 EMERGENCY BUG WORKFLOW (for immediate release)
283
4c0880b2 284The stable branch exists for easily making bug fix releases.
04437dba 285
286 git remote update
4c0880b2 287 git checkout -b topic/my-emergency-fix origin/master
04437dba 288 # hack
289 git commit
290
4c0880b2 291Then a cabal member merges into C<master>, and backports the change into
c5d6da29 292C<stable/X.YY>:
04437dba 293
4c0880b2 294 git checkout master
04437dba 295 git merge topic/my-emergency-fix
296 git push
c5d6da29 297 git checkout stable/X.YY
4c0880b2 298 git cherry-pick -x master
299 git push
04437dba 300 # release
04437dba 301
302=head1 PROJECT WORKFLOW
303
304For longer lasting branches, we use a subversion style branch layout, where
305master is routinely merged into the branch. Rebasing is allowed as long as all
5af926eb 306the branch contributors are using C<git pull --rebase> properly.
04437dba 307
308C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should
309only be done in topic branches. Committing to master is still done with the
310same review process as a topic branch, and the branch must merge as a fast
311forward.
312
9840bb38 313This is pretty much the way we're doing branches for large-ish things right
04437dba 314now.
315
316Obviously there is no technical limitation on the number of branches. You can
317freely create topic branches off of project branches, or sub projects inside
318larger projects freely. Such branches should incorporate the name of the branch
319they were made off so that people don't accidentally assume they should be
320merged into master:
321
322 git checkout -b my-project--topic/foo my-project
323
324(unfortunately Git will not allow C<my-project/foo> as a branch name if
325C<my-project> is a valid ref).
326
04437dba 327=head1 BRANCH ARCHIVAL
328
329Merged branches should be deleted.
330
daae2c87 331Failed branches may be kept, but should be moved to C<attic/> to differentiate
332them from in-progress topic branches.
04437dba 333
702e6744 334Branches that have not been worked on for a long time will be moved to
4c0880b2 335C<abandoned/> periodically, but feel free to move the branch back to C<topic/>
336if you want to start working on it again.
04437dba 337
600f7f85 338=head1 TESTS, TESTS, TESTS
339
aa2c2825 340If you write I<any> code for Moose, you B<must> add tests for that code. If you
341do not write tests then we cannot guarantee your change will not be removed or
342altered at a later date, as there is nothing to confirm this is desired
343behavior.
d85337ff 344
aa2c2825 345If your code change/addition is deep within the bowels of Moose and your test
346exercises this feature in a non-obvious way, please add some comments either
347near the code in question or in the test so that others know.
600f7f85 348
4c0880b2 349We also greatly appreciate documentation to go with your changes, and an entry
350in the Changes file. Make sure to give yourself credit! Major changes or new
351user-facing features should also be documented in L<Moose::Manual::Delta>.
600f7f85 352
daae2c87 353=head1 DOCS, DOCS, DOCS
354
355Any user-facing changes must be accompanied by documentation. If you're not
356comfortable writing docs yourself, you might be able to convince another Moose
357dev to help you.
358
359Our goal is to make sure that all features are documented. Undocumented
360features are not considered part of the API when it comes to determining
361whether a change is backwards compatible.
362
d85337ff 363=head1 BACKWARDS COMPATIBILITY
600f7f85 364
04437dba 365Change is inevitable, and Moose is not immune to this. We do our best
86b96832 366to maintain backwards compatibility, but we do not want the code base
d85337ff 367to become overburdened by this. This is not to say that we will be
368frivolous with our changes, quite the opposite, just that we are not
369afraid of change and will do our best to keep it as painless as
370possible for the end user.
600f7f85 371
4c0880b2 372Our policy for handling backwards compatibility is documented in more detail in
373L<Moose::Manual::Support>.
600f7f85 374
d85337ff 375All backwards incompatible changes B<must> be documented in
04437dba 376L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds
377for the change in that document.
600f7f85 378
d85337ff 379=cut