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.2015
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           git commit
326           dzil release # or dzil release --trial for trial releases
327
328       Release How-To
329
330       Moose uses Dist::Zilla to manage releases. Although the git repository
331       comes with a "Makefile.PL", it is a very basic one just to allow the
332       basic "perl Makefile.PL && make && make test" cycle to work. In
333       particular, it doesn't include any release metadata, such as
334       dependencies. In order to get started with Dist::Zilla, first install
335       it: "cpanm Dist::Zilla", and then install the plugins necessary for
336       reading the "dist.ini": "dzil authordeps | cpanm".
337
338       Moose releases fall into two categories, each with their own level of
339       release preparation. A minor release is one which does not include any
340       API changes, deprecations, and so on. In that case, it is sufficient to
341       simply test the release candidate against a few different Perls.
342       Testing should be done against at least two recent major versions of
343       Perl (5.8.8 and 5.10.1, for example). If you have more versions
344       available, you are encouraged to test them all. However, we do not put
345       a lot of effort into supporting older 5.8.x releases.
346
347       For major releases which include an API change or deprecation, you
348       should run the xt/author/test-my-dependents.t test. This tests a long
349       list of MooseX and other Moose-using modules from CPAN. In order to run
350       this script, you must arrange to have the new version of Moose in
351       Perl's include path. You can use "prove -b" and "prove -I", install the
352       module, or fiddle with the "PERL5LIB" environment variable, whatever
353       makes you happy.
354
355       This test downloads each module from CPAN, runs its tests, and logs
356       failures and warnings to a set of files named test-mydeps-$$-*.log. If
357       there are failures or warnings, please work with the authors of the
358       modules in question to fix them. If the module author simply isn't
359       available or does not want to fix the bug, it is okay to make a
360       release.
361
362       Regardless of whether or not a new module is available, any breakages
363       should be noted in the conflicts list in the distribution's dist.ini.
364
365   Emergency Bug Workflow (for immediate release)
366       The stable branch exists for easily making bug fix releases.
367
368           git remote update
369           git checkout -b topic/my-emergency-fix origin/master
370           # hack
371           git commit
372
373       Then a cabal member merges into "master", and backports the change into
374       "stable/X.YY":
375
376           git checkout master
377           git merge topic/my-emergency-fix
378           git push
379           git checkout stable/X.YY
380           git cherry-pick -x master
381           git push
382           # release
383
384   Project Workflow
385       For longer lasting branches, we use a subversion style branch layout,
386       where master is routinely merged into the branch. Rebasing is allowed
387       as long as all the branch contributors are using "git pull --rebase"
388       properly.
389
390       "commit --amend", "rebase --interactive", etc. are not allowed, and
391       should only be done in topic branches. Committing to master is still
392       done with the same review process as a topic branch, and the branch
393       must merge as a fast forward.
394
395       This is pretty much the way we're doing branches for large-ish things
396       right now.
397
398       Obviously there is no technical limitation on the number of branches.
399       You can freely create topic branches off of project branches, or sub
400       projects inside larger projects freely. Such branches should
401       incorporate the name of the branch they were made off so that people
402       don't accidentally assume they should be merged into master:
403
404           git checkout -b my-project--topic/foo my-project
405
406       (unfortunately Git will not allow "my-project/foo" as a branch name if
407       "my-project" is a valid ref).
408

BRANCH ARCHIVAL

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

TESTS, TESTS, TESTS

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

DOCS, DOCS, DOCS

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

BACKWARDS COMPATIBILITY

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

AUTHORS

460       •   Stevan Little <stevan@cpan.org>
461
462       •   Dave Rolsky <autarch@urth.org>
463
464       •   Jesse Luehrs <doy@cpan.org>
465
466       •   Shawn M Moore <sartak@cpan.org>
467
468       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
469
470       •   Karen Etheridge <ether@cpan.org>
471
472       •   Florian Ragwitz <rafl@debian.org>
473
474       •   Hans Dieter Pearcey <hdp@cpan.org>
475
476       •   Chris Prather <chris@prather.org>
477
478       •   Matt S Trout <mstrout@cpan.org>
479
481       This software is copyright (c) 2006 by Infinity Interactive, Inc.
482
483       This is free software; you can redistribute it and/or modify it under
484       the same terms as the Perl 5 programming language system itself.
485
486
487
488perl v5.34.0                      2021-07-22    Moose::Manual::Contributing(3)
Impressum