Dancer2::Development - Guide for developers interested in contributing to Dancer2
This guide has been written to help anyone interested in contributing to the development of Dancer2.
First of all - thank you for your interest in the project! It's the community of helpful contributors who've helped Dancer2 experience phenomenal growth to get to where it is today.
Please read this guide before contributing to Dancer2, to avoid wasted effort and maximizing the chances of your contributions being used.
There are many ways to contribute to the project. Dancer2 is a young yet active project and any kind of help is very much appreciated!
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 Dancer2.
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 Dancer2!).
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 Dancer2 user mailing list noted below.
Also, if you're using and enjoying Dancer2, http://cpanratings.perl.org/dist/Dancer2, explaining what you like about Dancer2 is another very valuable contribution that helps other new users find us!
Subscribing to the mailing list and/or hanging out on our IRC channel and providing assistance to new users is incredibly valuable.
irc.perl.org, or http://www.perldancer.org/irc for a quick web client.
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").
If you have access to perl on rare operating systems, please consider contributing tests. See http://wiki.cpantesters.org/wiki/TestDuringInstall for more information.
You can write extensions (plugins) for Dancer2 extending Dancer2's core functionality or contribute to Dancer2's core code, see "Patch Submission" below.
This section lists high-level recommendations for developing Dancer2, for more detailed guidelines, see "Coding Guidelines" below.
Dancer2 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.
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/Dancer2.html
If you find a failing test report, feel free to report it as a GitHub issue: http://github.com/PerlDancer/Dancer2/issues.
We prefer to have all our bug reports on GitHub, in the issues section: http://github.com/sukria/Dancer2/issues. It's possible though to report bugs on RT as well: https://rt.cpan.org/Dist/Display.html?Queue=Dancer2
Please make sure the bug you're reporting does not yet exist. In doubt please ask on IRC.
The Dancer2 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 Dancer2 quickly!
To help us achieve high-quality,
git-flow workflow is used to handle pull-requests,
that means contributors must work on their
devel branch rather than on their
(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
Here is the workflow for submitting a patch:
$ git clone git://github.com/myname/Dancer2.git
develbranch of your clone (
masteris used only for building releases).
$ git remote add upstream https://github.com/sukria/Dancer2.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.
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.
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
#dancer or http://www.perldancer.org/irc.
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!
A mailing list is available here: http://lists.perldancer.org/cgi-bin/listinfo/dancer-users
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.
The official repository is hosted on GitHub at the following location: http://github.com/PerlDancer/Dancer2.
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.
Dancer Core Developers
This software is copyright (c) 2013 by Alexis Sukrieh.