|o||Mailing list: <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users> to subscribe or view archives|
|o||IRC: #dancer on irc.perl.org, or <http://www.perldancer.org/irc> for a quick web client.|
While we value documentation very much, its 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 Dancer extending Dancers core functionality or contribute to Dancers core code, see Patch Submission below.
This section lists high-level recommendations for developing Dancer, for more detailed guidelines, see Coding Guidelines below.
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.
We can measure our quality using the CPAN testers platform: <http://www.cpantesters.org>.
If you find a failing test report, feel free to report it as a GitHub issue: <https://github.com/PerlDancer/Dancer/issues>.
We prefer to have all our bug reports on GitHub, in the issues section: <https://github.com/PerlDancer/Dancer/issues>. Its possible though to report bugs on RT as well: <https://rt.cpan.org/Dist/Display.html?Queue=Dancer>
Please make sure the bug youre reporting does not yet exist. In doubt please ask on IRC.
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:
o Fork the repository <https://github.com/PerlDancer/Dancer> (click Fork) o Clone your fork to have a local copy using the following command:
$ git clone git://github.com/myname/Dancer.git
o As a contributor, you should <B>alwaysB> 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, youll be immediately notified by git.
o 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 youre 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.
o Send a pull request via the GitHub interface. Make sure your pull request is based on the pr/$name branch youve just pushed, so that it incorporates the appropriate commits only.
Its 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>.
o When the core team reviews your pull request, it will either accept (and then merge into devel) or refuse your request.
If its 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 dont 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
Youre now ready to start working on a new pull request!
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.
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.
Thats 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 youve 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.
A mailing list is available here: <http://lists.preshweb.co.uk/mailman/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>. Were always happy to hear from users and contributors.
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:
Working with the devel branch
o master o devel
This is the development branch. New features are pushed here, and will be merged to master when the next release is being prepared.
However, you can run tests directly using the prove tool:
In most cases, prove is entirely sufficent for you to test any patches you have.
If you use cpanminus, you can do it without downloading the tarball first:
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:
You should then also install any additional requirements not needed by the dzil build but may be needed by tests or other development:
You can also do this via cpanm directly:
Once installed, here are some dzil commands you might try:
This Is Complicated. Is There an Easier Way?
$ 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 dont generate the tarball.
Actually, yes there is. You can also branch out directly from the <B>masterB> branch, which corresponds to the code is generated by Dist::Zilla and what is uploaded to CPAN. It wont contain any of the changes brought to the codebase since the last CPAN release, but for a small patch that shouldnt be a problem.
This section describes standards and requirements for coding. For more broad guidelines, see GENERAL DEVELOPMENT GUIDELINES above.
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 dont 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:
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 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 _).
For current information on Dancers plans for the future, see the file TODO at <https://github.com/PerlDancer/Dancer/blob/master/TODO>.
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.
|perl v5.20.3||DANCER::DEVELOPMENT (3)||2015-06-12|