Dancer2 Documentation

To release a new version of Dancer2, use the dzil release --all command. This command automates several critical steps, but it requires that the test suite passes completely before proceeding.

The dzil release --all command performs the following:

1. Runs the full test suite (including author tests).
2. Builds a tarball for upload to PAUSE.
3. Uploads the new version to PAUSE (requires PAUSE credentials to be configured).
4. Commits the updated Dancer2.pm and the new README file to your local repository.

Important Post-Release Step: After the command completes successfully, you must manually run git push to push the updated release files (the updated Dancer2.pm and README) to GitHub.

dzil release --all
# After success, run:
git push

Before running the release command, ensure the following preparation steps are completed:

1. Sync Code: Pull the latest code from main to ensure your environment is current.
2. Verify Merges: Ensure all issues and Pull Requests associated with the current GitHub milestone are closed. Move any pending items to a later release milestone if necessary.
3. Update Versioning: Update the version number in the dist.ini file following Semantic Versioning principles.
4. Check Credentials: Ensure your PAUSE credentials are set up for automated uploading. If they are not, you will need to manually update the release via the PAUSE web interface after the build step.

The plugins auto tests tool is a make script designed to test all Dancer plugins available on CPAN against both Dancer 1 and Dancer 2.

To ensure system stability, the tool installs Perl and the necessary Perl modules into a local directory (plugins_auto_test/perlbrew), leaving your system-wide Perl installation untouched.

Prerequisites:

• A *nix environment.
• make installed.
• perlbrew installed.
• An active Internet connection to access CPAN.

$ cd plugins_auto_test
$ make

Dancer2 provides several specialized documentation resources for different stages of development:

• Tutorial: A step-by-step guide from installation to a working application.
• Manual: A comprehensive reference for the framework.
• Keyword Guide (DSL): A complete list of all Dancer2 Domain Specific Language (DSL) keywords.
• Configuration Guide: A reference for all application configuration options.
• Deployment Guide: Instructions for hosting Dancer2 applications in real-world environments.
• Cookbook: Various recipes and common implementation patterns.
• Plugin Guide: A list of recommended plugins and guidance on how to author your own.

Dancer2 is a lightweight Perl web application framework. You can bootstrap a minimal application by using the Dancer2 module, defining routes with HTTP verbs (like get), and calling the dance method to start the application.

use Dancer2;
get '/' => sub { "Hello World" };
dance;

When merging Pull Requests or branches into Dancer2, follow these requirements to maintain release readiness:

• Test Integrity: Ensure all tests pass on the branch before merging.
• Changelog Accuracy: Update the Changes file. Every entry must include the relevant GitHub issue or PR number.
• Attribution: Ensure the author is correctly reflected in the Contributors section of Dancer2.pm.
• Merge Strategy: Use non-fast-forward merges: git merge --no-ff <branch-name> && git push.

When using the --git or --remote flag, the gen command performs the following actions:

1. Copies a .gitignore file from the Dancer2 distribution to your application directory.
2. Runs git init.
3. Runs git add ..
4. Runs git commit -m "Initial commit of <app_name> by Dancer2".
5. If --remote <URI> is provided, it runs git remote add origin <URI>.

Note: If Git initialization fails, you may need to manually run git init, git add ., and git commit within your application directory.

dancer2 gen -a my_app --git --remote git@github.com:user/my_app.git

To run a single Dancer2 application without middleware, use the to_app method on your application module. This converts the Dancer2 application into a Plack-compatible application object.

use My::App;

My::App->to_app;

To include middleware (such as Plack::Middleware::Deflater for compression), use Plack::Builder to wrap your Dancer2 application. Call to_app on your application module within the builder block.

use My::App;
use Plack::Builder;

builder {
    enable 'Deflater';
    My::App->to_app;
}

The gen command is a helper script used to scaffold a new Dancer2 application from a template (skeleton). It handles directory creation, file copying, template rendering, and optional integration with Git and Docker.

Usage

Run the command providing the required --application (or -a) name.

dancer2 gen --application my_app

Requirements

• Application Name: Must be a valid Perl module name (cannot contain single colons, dots, or hyphens, and cannot start with a number).
• Internet Access: By default, the command checks for the latest Dancer2 version on MetaCPAN. Use -x to skip this check.