{ "content": [ { "type": "text", "text": "# Moose::Manual::Contributing (perldoc)\n\n## NAME\n\nMoose::Manual::Contributing - How to get involved in Moose\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **GETTING INVOLVED** (4 subsections)\n- **WORKFLOWS** (5 subsections)\n- **BRANCH ARCHIVAL**\n- **BACKWARDS COMPATIBILITY**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Moose::Manual::Contributing", "section": "", "mode": "perldoc", "summary": "Moose::Manual::Contributing - How to get involved in Moose", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "GETTING INVOLVED", "lines": 3, "subsections": [ { "name": "Get the Code", "lines": 14 }, { "name": "People", "lines": 13 }, { "name": "New Features", "lines": 16 }, { "name": "Branch Layout", "lines": 41 } ] }, { "name": "WORKFLOWS", "lines": 1, "subsections": [ { "name": "Getting Started", "lines": 29 }, { "name": "Development Workflow", "lines": 78 }, { "name": "Approval Workflow", "lines": 51 }, { "name": "Release Workflow", "lines": 56 }, { "name": "Project Workflow", "lines": 20 } ] }, { "name": "BRANCH ARCHIVAL", "lines": 30, "subsections": [] }, { "name": "BACKWARDS COMPATIBILITY", "lines": 11, "subsections": [] }, { "name": "AUTHORS", "lines": 20, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Moose::Manual::Contributing - How to get involved in Moose\n", "subsections": [] }, "VERSION": { "content": "version 2.2200\n", "subsections": [] }, "GETTING INVOLVED": { "content": "Moose is an open project, and we are always willing to accept bug fixes, more tests, and\ndocumentation patches. Commit bits are given out freely and it's easy to get started!\n", "subsections": [ { "name": "Get the Code", "content": "If you just want to get your feet wet and check out the code, you can do so from the comfort of\nyour web browser by going to the official repository on GitHub:\n.\n\nHowever, if you know how to use git and would rather have a local copy (because, why wouldn't\nyou?!), then you can clone it:\n\ngit clone git@github.com:moose/Moose.git\n\nIf, at some point, you think you'd like to contribute a patch, please see \"Getting Started\".\n\n*NOTE: Your contribution is very important to us. If, for some reason, you would prefer not to\nuse Git/GitHub, come talk to us at #moose on irc.perl.org and we can work something out.*\n" }, { "name": "People", "content": "As Moose has matured, some structure has emerged in the process.\n\nCabal - people who can release moose\nThese people are the ones who have co-maint on Moose itself and can create a release.\nThey're listed under \"CABAL\" in Moose in the Moose documentation. They are responsible for\nreviewing branches, and are the only people who are allowed to push to stable branches.\n\nCabal members are listed in Moose and can often be found on irc in the\n channel.\n\nContributors - people creating a topic or branch\nYou!\n" }, { "name": "New Features", "content": "Moose already has a fairly large feature set, and we are currently not looking to add any major\nnew features to it. If you have an idea for a new feature in Moose, you are encouraged to create\na MooseX module first.\n\nAt this stage, no new features will even be considered for addition into the core without first\nbeing vetted as a MooseX module, unless it is absolutely 100% impossible to implement the\nfeature outside the core.\n\nIf you think it is 100% impossible, please come discuss it with us on IRC or via e-mail. Your\nfeature may need a small hook in the core, or a refactoring of some core modules, and we are\ndefinitely open to that.\n\nMoose was built from the ground up with the idea of being highly extensible, and quite often the\nfeature requests we see can be implemented through small extensions. Try it, it's much easier\nthan you might think.\n" }, { "name": "Branch Layout", "content": "The repository is divided into several branches to make maintenance easier for everyone\ninvolved. The branches below are ordered by level of stability.\n\nstable/*\nThe branch from which releases are cut. When making a new major release, the release manager\nmakes a new \"stable/X.YY\" branch at the current position of \"master\". The version used in\nthe stable branch should not include the last two digits of the version number.\n\nFor minor releases, patches will be committed to \"master\", and backported (cherry-picked) to\nthe appropriate stable branch as needed. A stable branch is only updated by someone from the\nCabal during a release.\n\nmaster\nThe main development branch. All new code should be written against this branch. This branch\ncontains code that has been reviewed, and will be included in the next major release.\nCommits which are judged to not break backwards compatibility may be backported into\n\"stable\" to be included in the next minor release.\n\ntopic/*\nSmall personal branches that are still in progress. They can be freely rebased. They contain\ntargeted features that may span a handful of commits. Any change or bugfix should be created\nin a topic branch.\n\nrfc/*\nTopic branches that are completed and waiting on review. A Cabal member will look over\nbranches in this namespace, and either merge them to \"master\" if they are acceptable, or\nmove them back to a different namespace otherwise. This namespace is being phased out now\nthat we are using GitHub's pull requests in our \"Development Workflow\".\n\nattic/*\nBranches which have been reviewed, and rejected. They remain in the repository in case we\nlater change our mind, or in case parts of them are still useful.\n\nabandoned/*\nTopic branches which have had no activity for a long period of time will be moved here, to\nkeep the main areas clean.\n\nLarger, longer term branches can also be created in the root namespace (i.e. at the same level\nas master and stable). This may be appropriate if multiple people are intending to work on the\nbranch. These branches should not be rebased without checking with other developers first.\n" } ] }, "WORKFLOWS": { "content": "", "subsections": [ { "name": "Getting Started", "content": "So, you've cloned the main Moose repository to your local machine (see \"Get the Code\") and\nyou're ready to do some hacking. We couldn't be happier to welcome you to our community!\n\nOf course, to ensure that your first experience is as productive and satisfying as possible, you\nshould probably take some time to read over this entire POD document. Doing so will give you a\nfull understanding of how Moose developers and maintainers work together and what they expect\nfrom one another. Done? Great!\n\nNext, assuming you have a GitHub account, go to and fork the\nrepository (see ). This will put an exact replica\nof the Moose repository into your GitHub account, which will serve as a place to publish your\npatches for the Moose maintainers to review and incorporate.\n\nOnce your fork has been created, switch to your local working repository directory and update\nyour \"origin\" remote's push URL. This allows you to use a single remote (\"origin\") to both pull\nin the latest code from GitHub and also push your work to your own fork:\n\n# Replace YOURUSERNAME below with your GitHub username\ngit remote set-url --push origin git@github.com:YOURUSERNAME/moose.git\n\nYou can verify your work:\n\n$ git remote -v\norigin git@github.com:moose/Moose.git (fetch)\norigin git@github.com:YOURUSERNAME/moose.git (push)\n\nNow, you're ready for action! From now on, you just follow the \"Development Workflow\" to publish\nyour work and submit pull requests to the Moose Cabal.\n" }, { "name": "Development Workflow", "content": "The general gist of the STANDARD WORKFLOW is:\n\n1. Update your local repository with the latest commits from the official repository\n2. Create a new topic branch, based on the master branch\n3. Hack away\n4. Commit and push the topic branch to your forked repository\n5. Submit a pull request through GitHub for that branch\n\nWhat follows is a more detailed rundown of that workflow. Please make sure to review and follow\nthe steps in the previous section, \"Getting Started\", if you have not done so already.\n\nUpdate Your Repository\nUpdate your local copy of the master branch from the remote:\n\ngit checkout master\ngit pull --rebase\n\nCreate Your Topic Branch\nNow, create a new topic branch based on your master branch. It's useful to use concise,\ndescriptive branch names such as: pod-syntax-contrib, feat-autodelegation, patch-23-role-comp,\netc. However, we'll just call ours \"my-feature\" for demonstration purposes:\n\ngit checkout -b topic/my-feature\n\nHack. Commit. Repeat.\nWhile you're hacking, the most important thing to remember is that your topic branch is yours to\ndo with as you like. Nothing you do there will affect anyone else at this point. Commit as often\nas little or as often as you need to and don't let perfection get in the way of progress.\nHowever, don't try to do too much as the easiest changes to integrate are small and focused.\n\nIf it's been a while since you created your topic branch, it's often a good idea to periodically\nrebase your branch off of the upstream master to reduce your work later on:\n\ngit fetch # or, git remote update\ngit rebase origin/master # or, git pull --rebase origin master\n\nYou should also feel free to publish (using \"push --force\" if necessary) your branch to your\nGitHub fork if you simply need feedback from others. (Note: actual collaboration takes a bit\nmore finesse and a lot less \"--force\" however).\n\nClean Up Your Branch\nFinally, when your development is done, it's time to prepare your branch for review. Even the\nsmallest branches can often use a little bit of tidying up before they are unleashed on a\nreviewer. Clarifying/cleaning up commit messages, reordering commits, splitting large commits or\nthose which contain different types of changes, squashing related or straggler commits are all\nhighly worthwhile activities to undertake on your topic branch.\n\nRemember: Your topic branch is yours. Don't worry about rewriting its history or breaking\nfast-forward. Some useful commands are listed below but please make sure that you understand\nwhat they do as they can rewrite history:\n\n- git commit --amend\n- git rebase --interactive\n- git cherry-pick\n\nUltimately, your goal in cleaning up your branch is to craft a set of commits whose content and\nmessages are as focused and understandable as possible. Doing so will greatly increase the\nchances of a speedy review and acceptance into the mainline development.\n\nRebase on the Latest\nBefore your final push and issuing a pull request, you need to ensure that your changes can be\neasily merged into the master branch of the upstream repository. This is done by once again\nrebasing your branch on the latest \"origin/master\".\n\ngit fetch # or, git remote update\ngit rebase origin/master # or, git pull --rebase origin master\n\nPublish and Pull Request\nNow it's time to make your final push of the branch to your fork. The \"--force\" flag is only\nnecessary if you've pushed before and subsequently rewriting your history:\n\ngit push --force\n\nAfter your branch is published, you can issue a pull request to the Moose Cabal. See\n for details.\n\nCongratulations! You're now a contributor!\n" }, { "name": "Approval Workflow", "content": "Moose is an open project but it is also an increasingly important one. Many modules depend on\nMoose being stable. Therefore, we have a basic set of criteria for reviewing and merging\nbranches. What follows is a set of rough guidelines that ensures all new code is properly vetted\nbefore it is merged to the master branch.\n\nIt should be noted that if you want your specific branch to be approved, it is your\nresponsibility to follow this process and advocate for your branch.\n\nSmall bug fixes, doc patches and additional passing tests.\nThese items don't really require approval beyond one of the core contributors just doing a\nsimple review. For especially simple patches (doc patches especially), committing directly\nto master is fine.\n\nLarger bug fixes, doc additions and TODO or failing tests.\nLarger bug fixes should be reviewed by at least one cabal member and should be tested using\nthe xt/author/test-my-dependents.t test.\n\nNew documentation is always welcome, but should also be reviewed by a cabal member for\naccuracy.\n\nTODO tests are basically feature requests, see our \"New Features\" section for more\ninformation on that. If your feature needs core support, create a \"topic/\" branch using the\n\"Development Workflow\" and start hacking away.\n\nFailing tests are basically bug reports. You should find a core contributor and/or cabal\nmember to see if it is a real bug, then submit the bug and your test to the RT queue. Source\ncontrol is not a bug reporting tool.\n\nNew user-facing features.\nAnything that creates a new user-visible feature needs to be approved by more than one cabal\nmember.\n\nMake sure you have reviewed \"New Features\" to be sure that you are following the guidelines.\nDo not be surprised if a new feature is rejected for the core.\n\nNew internals features.\nNew features for Moose internals are less restrictive than user facing features, but still\nrequire approval by at least one cabal member.\n\nIdeally you will have run the xt/author/test-my-dependents.t script to be sure you are not\nbreaking any MooseX module or causing any other unforeseen havoc. If you do this (rather\nthan make us do it), it will only help to hasten your branch's approval.\n\nBackwards incompatible changes.\nAnything that breaks backwards compatibility must be discussed by the cabal. Backwards\nincompatible changes should not be merged to master if there are strong objections from any\ncabal members.\n\nWe have a policy for what we see as sane \"BACKWARDS COMPATIBILITY\" for Moose. If your\nchanges break back-compat, you must be ready to discuss and defend your change.\n" }, { "name": "Release Workflow", "content": "# major releases (including trial releases)\ngit checkout master\n\n# minor releases\ngit checkout stable/X.YY\n\n# do final changelogging, etc\ngit commit\ndzil release # or dzil release --trial for trial releases\n\nRelease How-To\nMoose uses Dist::Zilla to manage releases. Although the git repository comes with a\n\"Makefile.PL\", it is a very basic one just to allow the basic \"perl Makefile.PL && make && make\ntest\" cycle to work. In particular, it doesn't include any release metadata, such as\ndependencies. In order to get started with Dist::Zilla, first install it: \"cpanm Dist::Zilla\",\nand then install the plugins necessary for reading the \"dist.ini\": \"dzil authordeps | cpanm\".\n\nMoose releases fall into two categories, each with their own level of release preparation. A\nminor release is one which does not include any API changes, deprecations, and so on. In that\ncase, it is sufficient to simply test the release candidate against a few different Perls.\nTesting should be done against at least two recent major versions of Perl (5.8.8 and 5.10.1, for\nexample). If you have more versions available, you are encouraged to test them all. However, we\ndo not put a lot of effort into supporting older 5.8.x releases.\n\nFor major releases which include an API change or deprecation, you should run the\nxt/author/test-my-dependents.t test. This tests a long list of MooseX and other Moose-using\nmodules from CPAN. In order to run this script, you must arrange to have the new version of\nMoose in Perl's include path. You can use \"prove -b\" and \"prove -I\", install the module, or\nfiddle with the \"PERL5LIB\" environment variable, whatever makes you happy.\n\nThis test downloads each module from CPAN, runs its tests, and logs failures and warnings to a\nset of files named test-mydeps-$$-*.log. If there are failures or warnings, please work with the\nauthors of the modules in question to fix them. If the module author simply isn't available or\ndoes not want to fix the bug, it is okay to make a release.\n\nRegardless of whether or not a new module is available, any breakages should be noted in the\nconflicts list in the distribution's dist.ini.\n\nEmergency Bug Workflow (for immediate release)\nThe stable branch exists for easily making bug fix releases.\n\ngit remote update\ngit checkout -b topic/my-emergency-fix origin/master\n# hack\ngit commit\n\nThen a cabal member merges into \"master\", and backports the change into \"stable/X.YY\":\n\ngit checkout master\ngit merge topic/my-emergency-fix\ngit push\ngit checkout stable/X.YY\ngit cherry-pick -x master\ngit push\n# release\n" }, { "name": "Project Workflow", "content": "For longer lasting branches, we use a subversion style branch layout, where master is routinely\nmerged into the branch. Rebasing is allowed as long as all the branch contributors are using\n\"git pull --rebase\" properly.\n\n\"commit --amend\", \"rebase --interactive\", etc. are not allowed, and should only be done in topic\nbranches. Committing to master is still done with the same review process as a topic branch, and\nthe branch must merge as a fast forward.\n\nThis is pretty much the way we're doing branches for large-ish things right now.\n\nObviously there is no technical limitation on the number of branches. You can freely create\ntopic branches off of project branches, or sub projects inside larger projects freely. Such\nbranches should incorporate the name of the branch they were made off so that people don't\naccidentally assume they should be merged into master:\n\ngit checkout -b my-project--topic/foo my-project\n\n(unfortunately Git will not allow \"my-project/foo\" as a branch name if \"my-project\" is a valid\nref).\n" } ] }, "BRANCH ARCHIVAL": { "content": "Merged branches should be deleted.\n\nFailed branches may be kept, but should be moved to \"attic/\" to differentiate them from\nin-progress topic branches.\n\nBranches that have not been worked on for a long time will be moved to \"abandoned/\"\nperiodically, but feel free to move the branch back to \"topic/\" if you want to start working on\nit again.\n\nTESTS, TESTS, TESTS\nIf you write *any* code for Moose, you must add tests for that code. If you do not write tests\nthen we cannot guarantee your change will not be removed or altered at a later date, as there is\nnothing to confirm this is desired behavior.\n\nIf your code change/addition is deep within the bowels of Moose and your test exercises this\nfeature in a non-obvious way, please add some comments either near the code in question or in\nthe test so that others know.\n\nWe also greatly appreciate documentation to go with your changes, and an entry in the Changes\nfile. Make sure to give yourself credit! Major changes or new user-facing features should also\nbe documented in Moose::Manual::Delta.\n\nDOCS, DOCS, DOCS\nAny user-facing changes must be accompanied by documentation. If you're not comfortable writing\ndocs yourself, you might be able to convince another Moose dev to help you.\n\nOur goal is to make sure that all features are documented. Undocumented features are not\nconsidered part of the API when it comes to determining whether a change is backwards\ncompatible.\n", "subsections": [] }, "BACKWARDS COMPATIBILITY": { "content": "Change is inevitable, and Moose is not immune to this. We do our best to maintain backwards\ncompatibility, but we do not want the code base to become overburdened by this. This is not to\nsay that we will be frivolous with our changes, quite the opposite, just that we are not afraid\nof change and will do our best to keep it as painless as possible for the end user.\n\nOur policy for handling backwards compatibility is documented in more detail in\nMoose::Manual::Support.\n\nAll backwards incompatible changes must be documented in Moose::Manual::Delta. Make sure to\ndocument any useful tips or workarounds for the change in that document.\n", "subsections": [] }, "AUTHORS": { "content": "* Stevan Little \n\n* Dave Rolsky \n\n* Jesse Luehrs \n\n* Shawn M Moore \n\n* יובל קוג'מן (Yuval Kogman) \n\n* Karen Etheridge \n\n* Florian Ragwitz \n\n* Hans Dieter Pearcey \n\n* Chris Prather \n\n* Matt S Trout \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is copyright (c) 2006 by Infinity Interactive, Inc.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n", "subsections": [] } } } }