1Moose::Manual::ContribuUtsienrg(C3o)ntributed Perl DocumMeonotsaet:i:oMnanual::Contributing(3)
2
6 Moose::Manual::Contributing - How to get involved in Moose
7
9 version 2.2015
10
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 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 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 git clone git@github.com:moose/Moose.git
25 If, at some point, you think you'd like to contribute a patch, please
27 see "Getting Started".
28 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 People
34 As Moose has matured, some structure has emerged in the process.
35 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 Cabal members are listed in Moose and can often be found on irc in
43 the <irc://irc.perl.org/#moose-dev> channel.
44 Contributors - people creating a topic or branch
46 You!
47 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 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 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 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 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 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 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 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 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 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 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 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 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
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 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 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 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 # Replace YOUR_USERNAME below with your GitHub username
145 git remote set-url --push origin git@github.com:YOUR_USERNAME/moose.git
146 You can verify your work:
148 $ git remote -v
150 origin git@github.com:moose/Moose.git (fetch)
151 origin git@github.com:YOUR_USERNAME/moose.git (push)
152 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 Development Workflow
158 The general gist of the STANDARD WORKFLOW is:
159 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 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 Update Your Repository
172 Update your local copy of the master branch from the remote:
174 git checkout master
176 git pull --rebase
177 Create Your Topic Branch
179 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 git checkout -b topic/my-feature
186 Hack. Commit. Repeat.
188 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 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 git fetch # or, git remote update
201 git rebase origin/master # or, git pull --rebase origin master
202 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 Clean Up Your Branch
209 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 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 - git commit --amend
224 - git rebase --interactive
225 - git cherry-pick
226 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 Rebase on the Latest
233 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 git fetch # or, git remote update
240 git rebase origin/master # or, git pull --rebase origin master
241 Publish and Pull Request
243 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 git push --force
249 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 Congratulations! You're now a contributor!
255 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 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 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 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 New documentation is always welcome, but should also be reviewed by
278 a cabal member for accuracy.
279 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 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 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 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 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 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 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 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 Release Workflow
318 # major releases (including trial releases)
319 git checkout master
320 # minor releases
322 git checkout stable/X.YY
323 # do final changelogging, etc
325 git commit
326 dzil release # or dzil release --trial for trial releases
327 Release How-To
329 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 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 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 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 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 Emergency Bug Workflow (for immediate release)
366 The stable branch exists for easily making bug fix releases.
367 git remote update
369 git checkout -b topic/my-emergency-fix origin/master
370 # hack
371 git commit
372 Then a cabal member merges into "master", and backports the change into
374 "stable/X.YY":
375 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 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 "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 This is pretty much the way we're doing branches for large-ish things
396 right now.
397 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 git checkout -b my-project--topic/foo my-project
405 (unfortunately Git will not allow "my-project/foo" as a branch name if
407 "my-project" is a valid ref).
408
410 Merged branches should be deleted.
411 Failed branches may be kept, but should be moved to "attic/" to
413 differentiate them from in-progress topic branches.
414 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
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 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 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
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 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
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 Our policy for handling backwards compatibility is documented in more
453 detail in Moose::Manual::Support.
454 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
460 • Stevan Little <stevan@cpan.org>
461 • Dave Rolsky <autarch@urth.org>
463 • Jesse Luehrs <doy@cpan.org>
465 • Shawn M Moore <sartak@cpan.org>
467 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
469 • Karen Etheridge <ether@cpan.org>
471 • Florian Ragwitz <rafl@debian.org>
473 • Hans Dieter Pearcey <hdp@cpan.org>
475 • Chris Prather <chris@prather.org>
477 • Matt S Trout <mstrout@cpan.org>
479
481 This software is copyright (c) 2006 by Infinity Interactive, Inc.
482 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.
485perl v5.34.0 2021-07-22 Moose::Manual::Contributing(3)