Publicity

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

• 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

Contribute to CPAN Testers

Code

Quality Assurance

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

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

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

Patch Submission

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!

Mailing Lists

IRC Channels

Repositories

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.

About Dependencies

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

Public Releases

Developer Releases

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