X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FContributing.pod;h=dfd2cf9b6100167f60ff5ab7f9ae70a29bfd0c5c;hb=b1fffd0f881c6bec7bad398d38dbac35c98f4f3c;hp=8bf7ffef9b1be3d2eb36593f386fbf7c6ffd7c00;hpb=d85337ff2425a77264f50ddcb336f94462668103;p=gitmo%2FMoose.git diff --git a/lib/Moose/Manual/Contributing.pod b/lib/Moose/Manual/Contributing.pod index 8bf7ffe..dfd2cf9 100644 --- a/lib/Moose/Manual/Contributing.pod +++ b/lib/Moose/Manual/Contributing.pod @@ -1,37 +1,24 @@ -=pod - -=head1 NAME +package Moose::Manual::Contributing; -Moose::Manual::Contributing - How to get involved in Moose - -=head1 GETTING INVOLVED +# ABSTRACT: How to get involved in Moose -Moose is a pretty open project and we are always willing to accept bug -fixes, more tests and doc patches. Doing these things is as simple as -cloning a copy of the git repository and hacking. +__END__ -Commit bits are given out freely. All we ask is that for any -non-trivial code patches, you check with one of the core developers -before applying said patch. - -Alternatively, you can make a new branch with your change and push it -back to the Moose git server, then ask a core dev to review your -branch. - -=head2 IRC and Email +=pod -A B of Moose discussion happens on IRC. We have two channels on -irc.perl.org, #moose and #moose-dev. The former is much more active, -but the core developers pay attention to both channels. +=head1 GETTING INVOLVED -We also have a mailing list, moose@perl.org and all the core -developers read and respond to messages on that list. +Moose is an open project, and we are always willing to accept bug fixes, +more tests, and documentation patches. Commit bits are given out freely, and +the L is very simple. The general gist is: clone the Git +repository, create a new topic branch, hack away, then find a committer to +review your changes. =head1 NEW FEATURES -Moose already has a fairly large feature set and we are currently +Moose already has a fairly large feature set, and we are currently B looking to add any major new features to it. If you have an -idea for a new feature in Moose, you are invited instead to create a +idea for a new feature in Moose, you are encouraged to create a MooseX module first. At this stage, no new features will even be considered for addition @@ -39,62 +26,354 @@ into the core without first being vetted as a MooseX module, unless it is absolutely 100% impossible to implement the feature outside the core. -If you think it is 100% impossible, you're probably wrong. However, -your feature may need a small hook in the core, or a refactoring of -some core modules, and we are definitely open to that. +If you think it is 100% impossible, please come discuss it with us on IRC or +via e-mail. Your feature may need a small hook in the core, or a +refactoring of some core modules, and we are definitely open to that. -Moose was built from the ground up with the idea of being highly -extensible, and quite often the feature requests we see can be -implemented through a couple of small and well placed extensions. Try -it, it is much easier then you might think. +Moose was built from the ground up with the idea of being highly extensible, +and quite often the feature requests we see can be implemented through small +extensions. Try it, it's much easier than you might think. -=head1 TESTS, TESTS, TESTS +=head1 PEOPLE -If you write I code for Moose or Class::MOP, you B add -tests for that code. If you do not write tests then we cannot -guarantee your change will not be removed or altered at a later date. +As Moose has matured, some structure has emerged in the process. -If your code change/addition is deep within the bowels of -Moose/Class::MOP and your test exercises this feature in a non-obvious -way, please add some comments either near the code in question or in -the test so that others know. +=over -We also greatly appreciate documentation to go with your changes, and -an entry in the Changes file. Make sure to give yourself credit! +=item Contributors - people creating a topic or branch -=head1 BACKWARDS COMPATIBILITY +You. -Change is inevitable and Moose is not immune to this. We do our best -to maintain backwards compatability, but we do not want the codebase -to become overburdened by this. This is not to say that we will be -frivolous with our changes, quite the opposite, just that we are not -afraid of change and will do our best to keep it as painless as -possible for the end user. +If you have commit access, you can create a topic on the main Moose.git +repository. If you don't have a commit bit, give us your SSH key or create your +own clone of the L repository. -The rule is that if you do something that is not backwards compatabile -you B do I one deprecation cycle (more if it is larger -change). For really larger or radical changes dev releases may be -needed as well (the core developers will decide on this on a -case-per-case basis). +The relevant repository URIs are: -The preference with regard to deprecation is to warn loudly and often -so that users will have time to fix their usages. +=over -All backwards incompatible changes B be documented in -L. Mke sure to document any useful tips or -workarounds for the change in that document. +=item Read-Only + +L + +=item Read+Write + +L + +=back + +=item Cabal - people who can release moose + +These people are the ones who have co-maint on Moose itself and can create a +release. They're listed under L in the Moose documentation. They +are responsible for reviewing branches, and are the only people who are allowed +to push to stable branches. + +Cabal members are listed in L and can often be found on irc in the +L channel. + +=back + +=head1 BRANCH LAYOUT + +The repository is divided into several branches to make maintenance easier for +everyone involved. The branches below are ordered by level of stability. + +=over + +=item stable/* + +The branch from which releases are cut. When making a new major release, the +release manager makes a new C branch at the current position of +C. The version used in the stable branch should not include the last +two digits of the version number. + +For minor releases, patches will be committed to C, and +backported (cherry-picked) to the appropriate stable branch as needed. A +stable branch is only updated by someone from the Cabal during a release. + +=item master + +The main development branch. All new code should be written against this +branch. This branch contains code that has been reviewed, and will be included +in the next major release. Commits which are judged to not break backwards +compatibility may be backported into C to be included in the next minor +release. + +=item rfc/* + +Topic branches that are completed and waiting on review. A Cabal member will +look over branches in this namespace, and either merge them to C if +they are acceptable, or move them back to a different namespace otherwise. + +=item topic/* + +Small personal branches that are still in progress. They can be freely rebased. +They contain targeted features that may span a handful of commits. Any change +or bugfix should be created in a topic branch. + +=item attic/* + +Branches which have been reviewed, and rejected. They remain in the repository +in case we later change our mind, or in case parts of them are still useful. + +=item abandoned/* + +Topic branches which have had no activity for a long period of time will be +moved here, to keep the main areas clean. + +=back + +Larger, longer term branches can also be created in the root namespace (i.e. +at the same level as master and stable). This may be appropriate if multiple +people are intending to work on the branch. These branches should not be +rebased without checking with other developers first. + +=head1 STANDARD WORKFLOW + + # update your copy of master + git checkout master + git pull --rebase + + # create a new topic branch + git checkout -b topic/my-feature + + # hack, commit, feel free to break fast forward + git commit --amend # allowed + git rebase --interactive # allowed + git push --force # allowed + + # keep the branch rebased on top of master, for easy reviewing + git remote update + git rebase origin/master + git push --force + + # when finished, move the branch to the rfc/ namespace + git branch -m rfc/my-feature + git push + git push origin :topic/my-feature + +When your branch is completed, make sure it has been moved to the C +namespace and is rebased on top of master, and ask for review/approval (see +L). If it is approved, the reviewer will merge it into +C. + +No actual merging (as in a human resolving conflicts) should be done when +merging into C, only from C into other branches. + +=head1 APPROVAL WORKFLOW + +Moose is an open project but it is also an increasingly important one. Many +modules depend on Moose being stable. Therefore, we have a basic set of +criteria for reviewing and merging branches. What follows is a set of rough +guidelines that ensures all new code is properly vetted before it is merged to +the master branch. + +It should be noted that if you want your specific branch to be approved, it is +B responsibility to follow this process and advocate for your branch. The +preferred way is to send a request to the mailing list for review/approval; +this allows us to better keep track of the branches awaiting approval and those +which have been approved. + +=over 4 + +=item Small bug fixes, doc patches and additional passing tests. -=head1 AUTHOR +These items don't really require approval beyond one of the core contributors +just doing a simple review. For especially simple patches (doc patches +especially), committing directly to master is fine. -Stevan Little Estevan@iinteractive.comE +=item Larger bug fixes, doc additions and TODO or failing tests. -=head1 COPYRIGHT AND LICENSE +Larger bug fixes should be reviewed by at least one cabal member and should be +tested using the F test. -Copyright 2009 by Infinity Interactive, Inc. +New documentation is always welcome, but should also be reviewed by a cabal +member for accuracy. -L +TODO tests are basically feature requests, see our L section +for more information on that. If your feature needs core support, create a +C branch using the L and start hacking away. -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. +Failing tests are basically bug reports. You should find a core contributor +and/or cabal member to see if it is a real bug, then submit the bug and your +test to the RT queue. Source control is not a bug reporting tool. + +=item New user-facing features. + +Anything that creates a new user-visible feature needs to be approved by +B cabal member. + +Make sure you have reviewed L to be sure that you are following +the guidelines. Do not be surprised if a new feature is rejected for the core. + +=item New internals features. + +New features for Moose internals are less restrictive than user facing +features, but still require approval by B cabal member. + +Ideally you will have run the F script to be sure you +are not breaking any MooseX module or causing any other unforeseen havoc. If +you do this (rather than make us do it), it will only help to hasten your +branch's approval. + +=item Backwards incompatible changes. + +Anything that breaks backwards compatibility must be discussed by the +cabal. Backwards incompatible changes should not be merged to master if there +are strong objections from any cabal members. + +We have a policy for what we see as sane L for +Moose. If your changes break back-compat, you must be ready to discuss and +defend your change. + +=back + +=head1 RELEASE WORKFLOW + + # major releases (including trial releases) + git checkout master + + # minor releases + git checkout stable/X.YY + + # do final changelogging, etc + vim dist.ini # increment version number + git commit + dzil release # or dzil release --trial for trial releases + git commit # to add the actual release date + git branch stable/X.YY # only for non-trial major releases + +=head2 Release How-To + +Moose uses L to manage releases. Although the git repository comes +with a C, it is a very basic one just to allow the basic +C cycle to work. In particular, it +doesn't include any release metadata, such as dependencies. In order to get +started with Dist::Zilla, first install it: C, and then +install the plugins necessary for reading the C: +C. + +Moose releases fall into two categories, each with their own level of release +preparation. A minor release is one which does not include any API changes, +deprecations, and so on. In that case, it is sufficient to simply test the +release candidate against a few different different Perls. Testing should be +done against at least two recent major version of Perl (5.8.8 and 5.10.1, for +example). If you have more versions available, you are encouraged to test them +all. However, we do not put a lot of effort into supporting older 5.8.x +releases. + +For major releases which include an API change or deprecation, you should run +the F test. This tests a long list of MooseX +and other Moose-using modules from CPAN. In order to run this script, you must +arrange to have the new version of Moose in Perl's include path. You can use +C and C, install the module, or fiddle with the C +environment variable, whatever makes you happy. + +This test downloads each module from CPAN, runs its tests, and logs failures +and warnings to a set of files named F. If there are +failures or warnings, please work with the authors of the modules in question +to fix them. If the module author simply isn't available or does not want to +fix the bug, it is okay to make a release. + +Regardless of whether or not a new module is available, any breakages should +be noted in the conflicts list in the distribution's F. + +=head1 EMERGENCY BUG WORKFLOW (for immediate release) + +The stable branch exists for easily making bug fix releases. + + git remote update + git checkout -b topic/my-emergency-fix origin/master + # hack + git commit + +Then a cabal member merges into C, and backports the change into +C: + + git checkout master + git merge topic/my-emergency-fix + git push + git checkout stable/X.YY + git cherry-pick -x master + git push + # release + +=head1 PROJECT WORKFLOW + +For longer lasting branches, we use a subversion style branch layout, where +master is routinely merged into the branch. Rebasing is allowed as long as all +the branch contributors are using C properly. + +C, C, etc. are not allowed, and should +only be done in topic branches. Committing to master is still done with the +same review process as a topic branch, and the branch must merge as a fast +forward. + +This is pretty much the way we're doing branches for large-ish things right +now. + +Obviously there is no technical limitation on the number of branches. You can +freely create topic branches off of project branches, or sub projects inside +larger projects freely. Such branches should incorporate the name of the branch +they were made off so that people don't accidentally assume they should be +merged into master: + + git checkout -b my-project--topic/foo my-project + +(unfortunately Git will not allow C as a branch name if +C is a valid ref). + +=head1 BRANCH ARCHIVAL + +Merged branches should be deleted. + +Failed branches may be kept, but should be moved to C to differentiate +them from in-progress topic branches. + +Branches that have not been worked on for a long time will be moved to +C periodically, but feel free to move the branch back to C +if you want to start working on it again. + +=head1 TESTS, TESTS, TESTS + +If you write I code for Moose, you B add tests for that code. If you +do not write tests then we cannot guarantee your change will not be removed or +altered at a later date, as there is nothing to confirm this is desired +behavior. + +If your code change/addition is deep within the bowels of Moose and your test +exercises this feature in a non-obvious way, please add some comments either +near the code in question or in the test so that others know. + +We also greatly appreciate documentation to go with your changes, and an entry +in the Changes file. Make sure to give yourself credit! Major changes or new +user-facing features should also be documented in L. + +=head1 DOCS, DOCS, DOCS + +Any user-facing changes must be accompanied by documentation. If you're not +comfortable writing docs yourself, you might be able to convince another Moose +dev to help you. + +Our goal is to make sure that all features are documented. Undocumented +features are not considered part of the API when it comes to determining +whether a change is backwards compatible. + +=head1 BACKWARDS COMPATIBILITY + +Change is inevitable, and Moose is not immune to this. We do our best +to maintain backwards compatibility, but we do not want the code base +to become overburdened by this. This is not to say that we will be +frivolous with our changes, quite the opposite, just that we are not +afraid of change and will do our best to keep it as painless as +possible for the end user. + +Our policy for handling backwards compatibility is documented in more detail in +L. + +All backwards incompatible changes B be documented in +L. Make sure to document any useful tips or workarounds +for the change in that document. =cut