Provided by: libdancer-perl_1.3500+dfsg-1_all bug

NAME

       Dancer::Development - guide for developers interested in contributing

VERSION

       version 1.3500

DESCRIPTION

       This guide has been written to help anyone interested in contributing to the development
       of Dancer.

       First of all - thank you for your interest in the project!  It's the community of helpful
       contributors who've helped Dancer experience phenomenal growth to get to where it is
       today.

       Please read this guide before contributing to Dancer, to avoid wasted effort and
       maximizing the chances of your contributions being used.

WAYS TO CONTRIBUTE

       There are many ways to contribute to the project. Dancer is a young yet active project and
       any kind of help is very much appreciated!

   Publicity
       You don't have to start by hacking the code, spreading the word is very valuable as well!

       If you have a blog, just feel free to speak about Dancer.

       If you're a Twitter user, you can tweet about it with the hashtag "#perl" (and feel free
       to follow @PerlDancer for news and updates on Dancer!).

       Of course, it doesn't have to be limited to blogs or Twitter.  Feel free to spread the
       word in whatever way you consider fit and drop us a line on the Dancer user mailing list
       noted below.

       Also, if you're using and enjoying Dancer, rating us on cpanratings.perl.org
       <http://cpanratings.perl.org/dist/Dancer>, explaining what you like about Dancer is
       another very valuable contribution that helps other new users find us!

   Mailing list / IRC community
       Subscribing to the mailing list and/or hanging out on our IRC channel and providing
       assistance to new users is incredibly valuable.

       ·   Mailing list: <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users> to subscribe
           or view archives

       ·   IRC: "#dancer" on "irc.perl.org", or <http://www.perldancer.org/irc> for a quick web
           client.

   Documentation
       While we value documentation very much, it's difficult to keep it up-to-date.  If you find
       a typo or an error in the documentation please do let us know - ideally by submitting a
       patch with your fix (see "Patch Submission").

   Contribute to CPAN Testers
       If you have access to perl on rare operating systems, please consider contributing tests.
       See <http://wiki.cpantesters.org/wiki/TestDuringInstall> for more information.

   Code
       You can write extensions (plugins) for Dancer extending Dancer's core functionality or
       contribute to Dancer's core code, see "Patch Submission" below.

GENERAL DEVELOPMENT GUIDELINES

       This section lists high-level recommendations for developing Dancer, for more detailed
       guidelines, see "Coding Guidelines" below.

   Quality Assurance
       Dancer should be able to install for all Perl versions since 5.8, on any platform for
       which Perl exists. We focus mainly on GNU/Linux (any distribution), *BSD and Windows
       (native and Cygwin).

       We should avoid regressions as much as possible and keep backwards compatibility in mind
       when refactoring. Stable releases should not break functionality and new releases should
       provide an upgrade path and upgrade tips such as warning the user about deprecated
       functionality.

   Quality Supervision
       We can measure our quality using the CPAN testers platform: <http://www.cpantesters.org>.

       A good way to help the project is to find a failing build log on the CPAN testers:
       <http://www.cpantesters.org/distro/D/Dancer.html>

       If you find a failing test report, feel free to report it as a GitHub issue:
       <https://github.com/PerlDancer/Dancer/issues>.

   Reporting Bugs
       We prefer to have all our bug reports on GitHub, in the issues section:
       <https://github.com/PerlDancer/Dancer/issues>. It's possible though to report bugs on RT
       as well: <https://rt.cpan.org/Dist/Display.html?Queue=Dancer>

       Please make sure the bug you're reporting does not yet exist. In doubt please ask on IRC.

   Patch Submission
       The Dancer development team uses GitHub to collaborate.  We greatly appreciate
       contributions submitted via GitHub, as it makes tracking these contributions and applying
       them much, much easier. This gives your contribution a much better chance of being
       integrated into Dancer quickly!

       To help us achieve high-quality, stable releases, git-flow workflow is used to handle
       pull-requests, that means contributors must work on their "devel" branch rather than on
       their "master".  (Master should be touched only by the core dev team when preparing a
       release to CPAN; all ongoing development happens in branches which are merged to the
       "devel" branch.)

       Here is the workflow for submitting a patch:

       ·   Fork the repository <https://github.com/PerlDancer/Dancer> (click "Fork")

       ·   Clone your fork to have a local copy using the following command:

               $ git clone git://github.com/myname/Dancer.git

       ·   As a contributor, you should always work on the "devel" branch of your clone ("master"
           is used only for building releases).

               $ git remote add upstream https://github.com/PerlDancer/Dancer.git
               $ git fetch upstream
               $ git checkout -b devel upstream/devel

           This will create a local branch in your clone named "devel" and that will track the
           official "devel" branch. That way, if you have more or less commits than the upstream
           repo, you'll be immediately notified by git.

       ·   You want to isolate all your commits in a topic branch, this will make the reviewing
           much easier for the core team and will allow you to continue working on your clone
           without worrying about different commits mixing together.

           To do that, first create a local branch to build your pull request:

               # you should be in devel here
               git checkout -b pr/$name

           Now you have created a local branch named pr/$name where $name is the name you want
           (it should describe the purpose of the pull request you're preparing).

           In that branch, do all the commits you need (the more the better) and when done, push
           the branch to your fork:

               # ... commits ...
               git push origin pr/$name

           You are now ready to send a pull request.

       ·   Send a pull request via the GitHub interface. Make sure your pull request is based on
           the pr/$name branch you've just pushed, so that it incorporates the appropriate
           commits only.

           It's also a good idea to summarize your work in a report sent to the users mailing
           list (see below), in order to make sure the team is aware of it.

           You could also notify the core team on IRC, on "irc.perl.org", channel "#dancer" or
           <http://www.perldancer.org/irc>.

       ·   When the core team reviews your pull request, it will either accept (and then merge
           into devel) or refuse your request.

           If it's refused, try to understand the reasons explained by the team for the denial.
           Most of the time, communicating with the core team is enough to understand what the
           mistake was. Above all, please don't be offended.

           If your pull-request is merged into devel, then all you have to do is to remove your
           local and remote pr/$name branch:

               git checkout devel
               git branch -D pr/$name
               git push origin :pr/$name

           And then, of course, you need to sync your local devel branch with the upstream:

               git pull upstream devel
               git push origin devel

           You're now ready to start working on a new pull request!

About the Release Cycle

       Since version 1.2, the team has decided to take a step further toward production concerns:
       Dancer now promises to provide an API-stable and feature frozen release, whose updates
       will only be about bugfixes and documentation updates.

       After some discussion with the core-team members, it has been agreed that the 1.2xx
       release series will be the first of this kind, and will live as long as 1.3xx lives.

       As soon as the last 1.3xx release is mature enough and the core team is happy with, it
       will be uploaded as the first version of the 1.4xx series, and 1.2xx will become obsolete.

       This lets us evolve quickly in our main track (devel in GitHub will contain all the daily
       work we want to make 1.3xx better) but as well, it lets us assure maintainability for the
       1.2 series, as we will probably have to fix a bug somewhere in 1.2 without merging with
       new stuff contained in the devel branch.

       That's why a maintenance branch is added to the repo. To be very clear, this branch is
       named "frozen", to reflect the idea that the source-code in this branch is not meant to
       evolve regarding features.  It should only contains fixes for bug or documentation
       updates.

       If you want to submit a pull-request to the frozen branch (that means 1.3xx is out and
       you've found a bug in 1.2xx) you need to base your work on the "frozen" branch. Use the
       same procedure explained before, but with the "frozen" branch.

RESOURCES FOR DEVELOPERS

   Mailing Lists
       A mailing list is available here:
       <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users>

   IRC Channels
       You can reach the development team on irc.perl.org, channel #dancer or via a web chat
       interface at <http://www.perldancer.org/irc>.  We're always happy to hear from users and
       contributors.

   Repositories
       The official repository is hosted on GitHub at the following location:
       <https://github.com/PerlDancer/Dancer>.

       Official developers have write access to this repository, contributors are invited to fork
       it if they want to submit patches, as explained in the Patch submission section.

       The repository layout is organized as follows:

       ·   "master"

           This branch is dedicated to prepare CPAN releases. We push to that branch only for
           packaging a new release. Every CPAN version are made from this branch.

       ·   "devel"

           This is the development branch. New features are pushed here, and will be merged to
           master when the next release is being prepared.

       Working with the devel branch

       The distribution is managed with Dist::Zilla.  This means than many of the usual files you
       might expect are not in the repository, but are generated at release time.

       However, you can run tests directly using the 'prove' tool:

           $ prove -l
           $ prove -lv t/some_test_file.t
           $ prove -lvr t/

       In most cases, 'prove' is entirely sufficient for you to test any patches you have.

       You may need to satisfy some dependencies. The easiest way to satisfy dependencies is to
       install the last release -- this is available at <https://metacpan.org/release/Dancer>.

       If you use cpanminus, you can do it without downloading the tarball first:

           $ cpanm --reinstall --installdeps --with-recommends Dancer

       Dist::Zilla is a very powerful authoring tool, but requires a number of author-specific
       plugins. If you would like to use it for contributing, install it from CPAN, then run one
       of the following commands, depending on your CPAN client:

           # with cpanminus
           $ dzil authordeps --missing | cpanm

           # with  cpan
           $ cpan `dzil authordeps --missing`

       You should then also install any additional requirements not needed by the dzil build but
       may be needed by tests or other development:

           # with cpanminus
           $ dzil listdeps --author --missing | cpanm

           # or just plain cpan...
           $ cpan `dzil listdeps --author --missing`

       You can also do this via cpanm directly:

           $ cpanm --reinstall --installdeps --with-develop --with-recommends Dancer

       Once installed, here are some dzil commands you might try:

       $ dzil build
           Build the code as it would appears on the final release.  The tarball of the new
           distribution will be present in the root directory of the repository, and a called
           "build/<this_branch">, where this_branch is the current working branch, will also have
           the product of the dzillification of the code.

       $ dzil test
           Run all tests in /t against the built code.

       $ dzil xtest
           Run the author tests (in /xt) against the built code.

       $ dzil listdeps --json
           List all the dependencies, in JSON.

       $ dzil build --notgz
           Build the code, but don't generate the tarball.

       This Is Complicated. Is There an Easier Way?

       Actually, yes there is. You can also branch out directly from the master branch, which
       corresponds to the code is generated by Dist::Zilla and what is uploaded to CPAN. It won't
       contain any of the changes brought to the codebase since the last CPAN release, but for a
       small patch that shouldn't be a problem.

CODING GUIDELINES

       This section describes standards and requirements for coding. For more broad guidelines,
       see "GENERAL DEVELOPMENT GUIDELINES" above.

   About Dependencies
       Dancer is intended to be a micro-framework. That means among other things that it should
       remain lightweight. For this reason we try very hard to keep the dependencies as low as
       possible. On the other hand, we don't want to reinvent the wheel either.

       We not likely to accept a new dependency to the core unless there is a very good reason.

       If a patch provides a new feature that depends on a module, the solution is to perform a
       dynamic loading. Dancer has a class dedicated to that job: Dancer::ModuleLoader. Here is
       an example of how to use it:

           package Dancer::Some::Thing;
           use Carp;

           sub init {
               Dancer::ModuleLoader->load('Some::Deps')
                   or croak "the feature provided by Dancer::Some::Thing needs Some::Deps";
           }

       That way, an optional feature doesn't block Dancer from being installed since the
       dependency check is performed at runtime.

   Perltidy
   Tests

RELEASING

   Public Releases
       Public and stable releases are those without an underline ('_') in the version number. The
       latest stable release can be downloaded from CPAN and github.com.

   Developer Releases
       Developer releases are those which include an underline ('_') in the version number.
       Whenever the devel branch has been merged into the master branch, the CPAN release built
       must be a developer version (the version number contains a '_').

       Before a new release is made, the uploaders must wait for the CPAN testers reports. This
       is done to make sure the new merge doesn't bring regressions.

   Roadmap
       For current information on Dancer's plans for the future, see the file TODO at
       <https://github.com/PerlDancer/Dancer/blob/master/TODO>.

AUTHOR

       Dancer Core Developers

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Alexis Sukrieh.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.