Dancer...lopment(3pm)

📦
version 1.3522 · 6 versions
, in ubuntu stonking

💖 NAME 💖

Dancer::Development — bestie, this is the guide for developers who wanna get in on contributing. It's from the User Contributed Perl Documentation set, and yes it's the (3pm) one. 🫶

✨ VERSION ✨

version 1.3522

🌸 DESCRIPTION 🌸

Okay so, this guide? Written for literally anyone who's interested in helping build Dancer. That's you. Hi. Welcome. 💅

First things first: thank you for caring about the project at all!! 😭 The whole reason Dancer grew the way it did — like, phenomenally — is the community of helpful contributors who showed up. That's not a vibe, that's a fact.

Please read this whole thing before you start contributing, though. Not to be that girl, but it genuinely saves wasted effort and it maxes out your chances of your contribution actually getting used. Main character move: read first, ship second. 👑

🌈 WAYS TO CONTRIBUTE 🌈

There are so many ways in. Dancer is a young-but-active project and literally any kind of help is very much appreciated!

📣 Publicity

You do not have to start by hacking on code. Spreading the word is highkey valuable too!

Got a blog? Feel free to just talk about Dancer. No permission needed, we're begging actually.

On Twitter? Tweet about it with the hashtag #perl — and feel free to follow @PerlDancer for news and updates on Dancer! 🦋

And of course it's not limited to blogs or Twitter. Spread the word however you think fits, and drop us a line on the Dancer user mailing list (linked below).

Also — if you're using Dancer and enjoying it, favorite us on MetaCPAN at https://metacpan.org/pod/Dancer. It costs you nothing and it means everything. 🥺

💬 Mailing list / IRC community

Subscribing to the mailing list and/or hanging out in our IRC channel and helping out new users? Incredibly valuable. Like, cannot overstate it.

📖 Documentation

We value docs so much, but keeping them up-to-date is genuinely hard. So if you spot a typo or an error in the documentation, please let us know — ideally by submitting a patch with your fix (peep "Patch Submission" below for how). 🎀

🧪 Contribute to CPAN Testers

If you've got access to perl on some rare operating system? Please consider contributing tests. More info lives at http://wiki.cpantesters.org/wiki/TestDuringInstall.

💻 Code

You can write extensions (plugins) for Dancer that extend Dancer's core functionality, or contribute to Dancer's core code itself. See "Patch Submission" below for the whole deal. 🔥

👑 GENERAL DEVELOPMENT GUIDELINES 👑

This section is the high-level recommendation zone for developing Dancer. Want the detailed stuff? Scroll to "Coding Guidelines" below. (It's in part 2, bestie, patience. 💜)

✅ Quality Assurance

Dancer should be able to install on all Perl versions since 5.8, on any platform where Perl exists. Periodt. Our main focus is GNU/Linux (any distribution), *BSD, and Windows (both native and Cygwin).

We should avoid regressions as much as humanly possible, and keep backwards compatibility in mind whenever we refactor. Stable releases should not break functionality, and new releases should provide an upgrade path plus upgrade tips — like warning the user about deprecated functionality. 🫶

🔍 Quality Supervision

We measure our quality using the CPAN testers platform: http://www.cpantesters.org.

A genuinely great way to help the project: go find a failing build log on CPAN testers at http://www.cpantesters.org/distro/D/Dancer.html.

Found a failing test report? Feel free to report it as a GitHub issue at 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. That said, it is possible to report bugs on RT as well: https://rt.cpan.org/Dist/Display.html?Queue=Dancer.

Please make sure the bug you're reporting doesn't already exist. In doubt? Just ask on IRC, we don't bite. 💅

🚀 Patch Submission

The Dancer development team uses GitHub to collaborate. We greatly appreciate contributions submitted via GitHub, because it makes tracking those contributions and applying them much, much easier. Which means your contribution has a way better chance of getting integrated into Dancer quickly! Slay.

To help us hit high-quality, stable releases, the 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 get merged to the devel branch.)

Here's the workflow for submitting a patch:

$ 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 it will track the official devel branch. That way, if you have more or fewer commits than the upstream repo, you'll be immediately notified by git. 🦋

  • You want to isolate all your commits in a topic branch. This makes reviewing way easier for the core team, and it lets you keep working on your clone without worrying about different commits mixing together. (Mixing commits? It's giving chaos. We don't do that here.)

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've created a local branch named pr/$name where $name is the name you want — and 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 you're 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 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), so the team is aware of it.

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

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

If it's refused, try to understand the reasons the team gave for the denial. Most of the time, just communicating with the core team is enough to understand what the mistake was. Above all: please don't be offended. It's never that deep, we promise. 💜

If your pull request is merged into devel, then all you have to do is 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! Iconic behavior, fr fr. ✨

🧊 About the Release Cycle 🧊

So since version 1.2, the team 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 was agreed that the 1.2xx release series would be the first of this kind, and it 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, 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 also lets us assure maintainability for the 1.2 series — because we'll probably have to fix a bug somewhere in 1.2 without merging in the 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 contain fixes for bugs 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. Simple as that, bestie. 🎀

✨ RESOURCES FOR DEVELOPERS ✨

okay bestie, here's where to find the Dancer devs and how to slide into the codebase. 💖

Mailing Lists

There's a mailing list, and it lives right 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 repo is hosted on GitHub at:

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.

Repo layout is giving structure, and it's organized like this:

  • master — This branch is dedicated to prepare CPAN releases. We push to that branch only for packaging a new release. Every CPAN version is 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. That means many of the usual files you might expect are not in the repository, but are generated at release time. It's giving magic, ngl. ✨

But 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. lowkey a lifesaver. 🫶

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. (Yes, that's the original energy — we're picky about deps. 🧐)

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. iconic. 💖

Perltidy

(The original page just names this one and dips. No extra deets here, bestie.)

Tests

(Same vibe — just the heading, no extra tea in the original.)

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. slay. ✨

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. no cap, tests are the vibe check. 🫶

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

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.

And that's the whole page, bestie. Source: perl v5.40.1. Date: 2026-05-05. Page: Dancer...lopment(3pm). Stay iconic, keep slaying, and may your patches always pass. 💅✨

📦 where this page comes from