1Moose::Manual::ContribuUtsienrg(C3o)ntributed Perl DocumMeonotsaet:i:oMnanual::Contributing(3)
2
3
4

NAME

6       Moose::Manual::Contributing - How to get involved in Moose
7

VERSION

9       version 2.2011
10

GETTING INVOLVED

12       Moose is an open project, and we are always willing to accept bug
13       fixes, more tests, and documentation patches. Commit bits are given out
14       freely and it's easy to get started!
15
16   Get the Code
17       If you just want to get your feet wet and check out the code, you can
18       do so from the comfort of your web browser by going to the official
19       repository on GitHub: <https://github.com/moose/Moose>.
20
21       However, if you know how to use git and would rather have a local copy
22       (because, why wouldn't you?!), then you can clone it:
23
24           git clone git@github.com:moose/Moose.git
25
26       If, at some point, you think you'd like to contribute a patch, please
27       see "Getting Started".
28
29       NOTE: Your contribution is very important to us. If, for some reason,
30       you would prefer not to use Git/GitHub, come talk to us at #moose on
31       irc.perl.org and we can work something out.
32
33   People
34       As Moose has matured, some structure has emerged in the process.
35
36       Cabal - people who can release moose
37           These people are the ones who have co-maint on Moose itself and can
38           create a release. They're listed under "CABAL" in Moose in the
39           Moose documentation. They are responsible for reviewing branches,
40           and are the only people who are allowed to push to stable branches.
41
42           Cabal members are listed in Moose and can often be found on irc in
43           the <irc://irc.perl.org/#moose-dev> channel.
44
45       Contributors - people creating a topic or branch
46           You!
47
48   New Features
49       Moose already has a fairly large feature set, and we are currently not
50       looking to add any major new features to it. If you have an idea for a
51       new feature in Moose, you are encouraged to create a MooseX module
52       first.
53
54       At this stage, no new features will even be considered for addition
55       into the core without first being vetted as a MooseX module, unless it
56       is absolutely 100% impossible to implement the feature outside the
57       core.
58
59       If you think it is 100% impossible, please come discuss it with us on
60       IRC or via e-mail. Your feature may need a small hook in the core, or a
61       refactoring of some core modules, and we are definitely open to that.
62
63       Moose was built from the ground up with the idea of being highly
64       extensible, and quite often the feature requests we see can be
65       implemented through small extensions. Try it, it's much easier than you
66       might think.
67
68   Branch Layout
69       The repository is divided into several branches to make maintenance
70       easier for everyone involved. The branches below are ordered by level
71       of stability.
72
73       stable/*
74           The branch from which releases are cut. When making a new major
75           release, the release manager makes a new "stable/X.YY" branch at
76           the current position of "master". The version used in the stable
77           branch should not include the last two digits of the version
78           number.
79
80           For minor releases, patches will be committed to "master", and
81           backported (cherry-picked) to the appropriate stable branch as
82           needed. A stable branch is only updated by someone from the Cabal
83           during a release.
84
85       master
86           The main development branch. All new code should be written against
87           this branch. This branch contains code that has been reviewed, and
88           will be included in the next major release. Commits which are
89           judged to not break backwards compatibility may be backported into
90           "stable" to be included in the next minor release.
91
92       topic/*
93           Small personal branches that are still in progress. They can be
94           freely rebased.  They contain targeted features that may span a
95           handful of commits. Any change or bugfix should be created in a
96           topic branch.
97
98       rfc/*
99           Topic branches that are completed and waiting on review. A Cabal
100           member will look over branches in this namespace, and either merge
101           them to "master" if they are acceptable, or move them back to a
102           different namespace otherwise.  This namespace is being phased out
103           now that we are using GitHub's pull requests in our "Development
104           Workflow".
105
106       attic/*
107           Branches which have been reviewed, and rejected. They remain in the
108           repository in case we later change our mind, or in case parts of
109           them are still useful.
110
111       abandoned/*
112           Topic branches which have had no activity for a long period of time
113           will be moved here, to keep the main areas clean.
114
115       Larger, longer term branches can also be created in the root namespace
116       (i.e.  at the same level as master and stable). This may be appropriate
117       if multiple people are intending to work on the branch. These branches
118       should not be rebased without checking with other developers first.
119

WORKFLOWS

121   Getting Started
122       So, you've cloned the main Moose repository to your local machine (see
123       "Get the Code") and you're ready to do some hacking. We couldn't be
124       happier to welcome you to our community!
125
126       Of course, to ensure that your first experience is as productive and
127       satisfying as possible, you should probably take some time to read over
128       this entire POD document. Doing so will give you a full understanding
129       of how Moose developers and maintainers work together and what they
130       expect from one another. Done?  Great!
131
132       Next, assuming you have a GitHub account, go to
133       <http://github.com/moose/Moose> and fork the repository (see
134       <https://help.github.com/articles/fork-a-repo>). This will put an exact
135       replica of the Moose repository into your GitHub account, which will
136       serve as a place to publish your patches for the Moose maintainers to
137       review and incorporate.
138
139       Once your fork has been created, switch to your local working
140       repository directory and update your "origin" remote's push URL. This
141       allows you to use a single remote ("origin") to both pull in the latest
142       code from GitHub and also push your work to your own fork:
143
144           # Replace YOUR_USERNAME below with your GitHub username
145           git remote set-url --push origin git@github.com:YOUR_USERNAME/moose.git
146
147       You can verify your work:
148
149           $ git remote -v
150           origin  git@github.com:moose/Moose.git (fetch)
151           origin  git@github.com:YOUR_USERNAME/moose.git (push)
152
153       Now, you're ready for action!  From now on, you just follow the
154       "Development Workflow" to publish your work and submit pull requests to
155       the Moose Cabal.
156
157   Development Workflow
158       The general gist of the STANDARD WORKFLOW is:
159
160       1. Update your local repository with the latest commits from the
161       official repository
162       2. Create a new topic branch, based on the master branch
163       3. Hack away
164       4. Commit and push the topic branch to your forked repository
165       5. Submit a pull request through GitHub for that branch
166
167       What follows is a more detailed rundown of that workflow. Please make
168       sure to review and follow the steps in the previous section, "Getting
169       Started", if you have not done so already.
170
171       Update Your Repository
172
173       Update your local copy of the master branch from the remote:
174
175           git checkout master
176           git pull --rebase
177
178       Create Your Topic Branch
179
180       Now, create a new topic branch based on your master branch. It's useful
181       to use concise, descriptive branch names such as: pod-syntax-contrib,
182       feat-autodelegation, patch-23-role-comp, etc. However, we'll just call
183       ours "my-feature" for demonstration purposes:
184
185           git checkout -b topic/my-feature
186
187       Hack. Commit. Repeat.
188
189       While you're hacking, the most important thing to remember is that your
190       topic branch is yours to do with as you like. Nothing you do there will
191       affect anyone else at this point. Commit as often as little or as often
192       as you need to and don't let perfection get in the way of progress.
193       However, don't try to do too much as the easiest changes to integrate
194       are small and focused.
195
196       If it's been a while since you created your topic branch, it's often a
197       good idea to periodically rebase your branch off of the upstream master
198       to reduce your work later on:
199
200           git fetch                   # or, git remote update
201           git rebase origin/master    # or, git pull --rebase origin master
202
203       You should also feel free to publish (using "push --force" if
204       necessary) your branch to your GitHub fork if you simply need feedback
205       from others. (Note: actual collaboration takes a bit more finesse and a
206       lot less "--force" however).
207
208       Clean Up Your Branch
209
210       Finally, when your development is done, it's time to prepare your
211       branch for review. Even the smallest branches can often use a little
212       bit of tidying up before they are unleashed on a reviewer.
213       Clarifying/cleaning up commit messages, reordering commits, splitting
214       large commits or those which contain different types of changes,
215       squashing related or straggler commits are all highly worthwhile
216       activities to undertake on your topic branch.
217
218       Remember: Your topic branch is yours. Don't worry about rewriting its
219       history or breaking fast-forward. Some useful commands are listed below
220       but please make sure that you understand what they do as they can
221       rewrite history:
222
223           - git commit --amend
224           - git rebase --interactive
225           - git cherry-pick
226
227       Ultimately, your goal in cleaning up your branch is to craft a set of
228       commits whose content and messages are as focused and understandable as
229       possible.  Doing so will greatly increase the chances of a speedy
230       review and acceptance into the mainline development.
231
232       Rebase on the Latest
233
234       Before your final push and issuing a pull request, you need to ensure
235       that your changes can be easily merged into the master branch of the
236       upstream repository. This is done by once again rebasing your branch on
237       the latest "origin/master".
238
239           git fetch                   # or, git remote update
240           git rebase origin/master    # or, git pull --rebase origin master
241
242       Publish and Pull Request
243
244       Now it's time to make your final push of the branch to your fork. The
245       "--force" flag is only necessary if you've pushed before and
246       subsequently rewriting your history:
247
248           git push --force
249
250       After your branch is published, you can issue a pull request to the
251       Moose Cabal. See <https://help.github.com/articles/using-pull-requests>
252       for details.
253
254       Congratulations! You're now a contributor!
255
256   Approval Workflow
257       Moose is an open project but it is also an increasingly important one.
258       Many modules depend on Moose being stable. Therefore, we have a basic
259       set of criteria for reviewing and merging branches. What follows is a
260       set of rough guidelines that ensures all new code is properly vetted
261       before it is merged to the master branch.
262
263       It should be noted that if you want your specific branch to be
264       approved, it is your responsibility to follow this process and advocate
265       for your branch.
266
267       Small bug fixes, doc patches and additional passing tests.
268           These items don't really require approval beyond one of the core
269           contributors just doing a simple review. For especially simple
270           patches (doc patches especially), committing directly to master is
271           fine.
272
273       Larger bug fixes, doc additions and TODO or failing tests.
274           Larger bug fixes should be reviewed by at least one cabal member
275           and should be tested using the xt/author/test-my-dependents.t test.
276
277           New documentation is always welcome, but should also be reviewed by
278           a cabal member for accuracy.
279
280           TODO tests are basically feature requests, see our "New Features"
281           section for more information on that. If your feature needs core
282           support, create a "topic/" branch using the "Development Workflow"
283           and start hacking away.
284
285           Failing tests are basically bug reports. You should find a core
286           contributor and/or cabal member to see if it is a real bug, then
287           submit the bug and your test to the RT queue. Source control is not
288           a bug reporting tool.
289
290       New user-facing features.
291           Anything that creates a new user-visible feature needs to be
292           approved by more than one cabal member.
293
294           Make sure you have reviewed "New Features" to be sure that you are
295           following the guidelines. Do not be surprised if a new feature is
296           rejected for the core.
297
298       New internals features.
299           New features for Moose internals are less restrictive than user
300           facing features, but still require approval by at least one cabal
301           member.
302
303           Ideally you will have run the xt/author/test-my-dependents.t script
304           to be sure you are not breaking any MooseX module or causing any
305           other unforeseen havoc. If you do this (rather than make us do it),
306           it will only help to hasten your branch's approval.
307
308       Backwards incompatible changes.
309           Anything that breaks backwards compatibility must be discussed by
310           the cabal. Backwards incompatible changes should not be merged to
311           master if there are strong objections from any cabal members.
312
313           We have a policy for what we see as sane "BACKWARDS COMPATIBILITY"
314           for Moose. If your changes break back-compat, you must be ready to
315           discuss and defend your change.
316
317   Release Workflow
318           # major releases (including trial releases)
319           git checkout master
320
321           # minor releases
322           git checkout stable/X.YY
323
324           # do final changelogging, etc
325           vim dist.ini # increment version number
326           git commit
327           dzil release # or dzil release --trial for trial releases
328           git commit # to add the actual release date
329           git branch stable/X.YY # only for non-trial major releases
330
331       Release How-To
332
333       Moose uses Dist::Zilla to manage releases. Although the git repository
334       comes with a "Makefile.PL", it is a very basic one just to allow the
335       basic "perl Makefile.PL && make && make test" cycle to work. In
336       particular, it doesn't include any release metadata, such as
337       dependencies. In order to get started with Dist::Zilla, first install
338       it: "cpanm Dist::Zilla", and then install the plugins necessary for
339       reading the "dist.ini": "dzil authordeps | cpanm".
340
341       Moose releases fall into two categories, each with their own level of
342       release preparation. A minor release is one which does not include any
343       API changes, deprecations, and so on. In that case, it is sufficient to
344       simply test the release candidate against a few different Perls.
345       Testing should be done against at least two recent major versions of
346       Perl (5.8.8 and 5.10.1, for example). If you have more versions
347       available, you are encouraged to test them all. However, we do not put
348       a lot of effort into supporting older 5.8.x releases.
349
350       For major releases which include an API change or deprecation, you
351       should run the xt/author/test-my-dependents.t test. This tests a long
352       list of MooseX and other Moose-using modules from CPAN. In order to run
353       this script, you must arrange to have the new version of Moose in
354       Perl's include path. You can use "prove -b" and "prove -I", install the
355       module, or fiddle with the "PERL5LIB" environment variable, whatever
356       makes you happy.
357
358       This test downloads each module from CPAN, runs its tests, and logs
359       failures and warnings to a set of files named test-mydeps-$$-*.log. If
360       there are failures or warnings, please work with the authors of the
361       modules in question to fix them. If the module author simply isn't
362       available or does not want to fix the bug, it is okay to make a
363       release.
364
365       Regardless of whether or not a new module is available, any breakages
366       should be noted in the conflicts list in the distribution's dist.ini.
367
368   Emergency Bug Workflow (for immediate release)
369       The stable branch exists for easily making bug fix releases.
370
371           git remote update
372           git checkout -b topic/my-emergency-fix origin/master
373           # hack
374           git commit
375
376       Then a cabal member merges into "master", and backports the change into
377       "stable/X.YY":
378
379           git checkout master
380           git merge topic/my-emergency-fix
381           git push
382           git checkout stable/X.YY
383           git cherry-pick -x master
384           git push
385           # release
386
387   Project Workflow
388       For longer lasting branches, we use a subversion style branch layout,
389       where master is routinely merged into the branch. Rebasing is allowed
390       as long as all the branch contributors are using "git pull --rebase"
391       properly.
392
393       "commit --amend", "rebase --interactive", etc. are not allowed, and
394       should only be done in topic branches. Committing to master is still
395       done with the same review process as a topic branch, and the branch
396       must merge as a fast forward.
397
398       This is pretty much the way we're doing branches for large-ish things
399       right now.
400
401       Obviously there is no technical limitation on the number of branches.
402       You can freely create topic branches off of project branches, or sub
403       projects inside larger projects freely. Such branches should
404       incorporate the name of the branch they were made off so that people
405       don't accidentally assume they should be merged into master:
406
407           git checkout -b my-project--topic/foo my-project
408
409       (unfortunately Git will not allow "my-project/foo" as a branch name if
410       "my-project" is a valid ref).
411

BRANCH ARCHIVAL

413       Merged branches should be deleted.
414
415       Failed branches may be kept, but should be moved to "attic/" to
416       differentiate them from in-progress topic branches.
417
418       Branches that have not been worked on for a long time will be moved to
419       "abandoned/" periodically, but feel free to move the branch back to
420       "topic/" if you want to start working on it again.
421

TESTS, TESTS, TESTS

423       If you write any code for Moose, you must add tests for that code. If
424       you do not write tests then we cannot guarantee your change will not be
425       removed or altered at a later date, as there is nothing to confirm this
426       is desired behavior.
427
428       If your code change/addition is deep within the bowels of Moose and
429       your test exercises this feature in a non-obvious way, please add some
430       comments either near the code in question or in the test so that others
431       know.
432
433       We also greatly appreciate documentation to go with your changes, and
434       an entry in the Changes file. Make sure to give yourself credit! Major
435       changes or new user-facing features should also be documented in
436       Moose::Manual::Delta.
437

DOCS, DOCS, DOCS

439       Any user-facing changes must be accompanied by documentation. If you're
440       not comfortable writing docs yourself, you might be able to convince
441       another Moose dev to help you.
442
443       Our goal is to make sure that all features are documented. Undocumented
444       features are not considered part of the API when it comes to
445       determining whether a change is backwards compatible.
446

BACKWARDS COMPATIBILITY

448       Change is inevitable, and Moose is not immune to this. We do our best
449       to maintain backwards compatibility, but we do not want the code base
450       to become overburdened by this. This is not to say that we will be
451       frivolous with our changes, quite the opposite, just that we are not
452       afraid of change and will do our best to keep it as painless as
453       possible for the end user.
454
455       Our policy for handling backwards compatibility is documented in more
456       detail in Moose::Manual::Support.
457
458       All backwards incompatible changes must be documented in
459       Moose::Manual::Delta. Make sure to document any useful tips or
460       workarounds for the change in that document.
461

AUTHORS

463       ·   Stevan Little <stevan.little@iinteractive.com>
464
465       ·   Dave Rolsky <autarch@urth.org>
466
467       ·   Jesse Luehrs <doy@tozt.net>
468
469       ·   Shawn M Moore <code@sartak.org>
470
471       ·   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
472
473       ·   Karen Etheridge <ether@cpan.org>
474
475       ·   Florian Ragwitz <rafl@debian.org>
476
477       ·   Hans Dieter Pearcey <hdp@weftsoar.net>
478
479       ·   Chris Prather <chris@prather.org>
480
481       ·   Matt S Trout <mst@shadowcat.co.uk>
482
484       This software is copyright (c) 2006 by Infinity Interactive, Inc.
485
486       This is free software; you can redistribute it and/or modify it under
487       the same terms as the Perl 5 programming language system itself.
488
489
490
491perl v5.28.0                      2018-05-16    Moose::Manual::Contributing(3)
Impressum