/ 
Dancer-1.3000_01
River stage three • 211 direct dependents • 215 total dependents
/ Dancer::Development

NAME

Dancer::Development - guide for developers interested in contributing

DESCRIPTION

This guide has been written to help developers of the project in their daily needs. This guide is the reference for any developer working on Dancer.

If you want to contribute code to Dancer you should first start by reading this guide.

HOW TO CONTRIBUTE

There are many ways to contribute to the project. Dancer is a young yet avtice project and any kind of help is appreciated.

Marketing

You don't have to start by hacking the code, spreadign the good words in valuable as well. 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.

Documentation

We do give lots of importance to documentation, but it's difficult to keep it up-to-date and error-prone. If you find a typo or an error in a documentation you can submit a patch with your fix (see "Patch submission").

Quality Assurance

We call "Quality Assurance" the fact that we keep in mind that Dancer should ne able to install into all version of Perl since Perl 5.8, on any platforms.

We should avoid as much as possible regressions and backward compatibility should be always in mind when refactoring.

Quality supervision

Our weapon for being aware of our quality is 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/Dancer.html

If you find a failing test report, feel free to report it as a GitHub issue: http://github.com/sukria/Dancer/issues.

Reporting bugs

We prefer to have all our bug reports on GitHub, in the issues section: <http://github.com/sukria/Dancer/issues>. It's possible though to report bugs on RT as well: https://rt.cpan.org/Dist/Display.html?Queue=Dancer

Please make sure the bug you're reporting is not yet present, in doubt ask on IRC.

Patch submission

The Dancer's development team uses GitHub to collaborate. Any contribution must be submited via GitHub.

In order to make the life of Dancer's integrator easier, git-flow is used to handle pull-requests, that means each contributor must work on their devel branch rather than on their master.

Here is the workflow for submitting a patch:

  • Fork the repository http://github.com/sukria/Dancer

  • Clone your fork like the following:

    $ git clone <PATH_TOUR_GIT_CLONE>
$ cd Dancer

  • 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/sukria/Dancer.git
    $ git checkout -b devel upstream/devel

    This will create a local branch in your clone named devel and that will track the offical devel branch. That way, if you have more or less commits than the upstream repo, you'll be immediatly 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 on 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.

    It's also a good idea to summarize your work in a report sent to the users mailing list, in order to make sure the team is aware of it.

    At least, you can notify the core team on IRC, on irc.perl.org, chan #dancer.

  • When the core team review your pull request, either it will be accepted (and then merged into devel) or refused.

    If it's refused, make sure 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 was the mistake.

    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!

About the releases cycle

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 releases serie will be the first of this kind, and will live as long as 1.3xx lives.

As soon as the last 1.3xx release is mature enough and tha the core team is happy with, it will be uploaded as the first version of the 1.4xx series, and 1.2xx will become obsolete.

This let us evolves 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 thr 1.2 series, as we will propably have to fix a bug somewhere in 1.2 without merging with 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 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 you've found a bug in 1.2xx) you need to base your work on the frozen branch. Use the same procdure explained before, but with the frozen branch.

RESOURCES FOR DEVELOPERS

Mailing lists

A mailing list is available here: http://lists.perldancer.org/cgi-bin/listinfo/dancer-users

IRC channels

You can reach the development team on irc.perl.org, chan #dancer.

Repositories

The official repository is hosted on GitHub at the following location: http://github.com/sukria/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:

  • 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. Every new feature are supposed to be first pushed to that branch.

CODING GUIDELINES

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 dependency bag as low as possible. But we don't want either to reinvent the wheel.

The balance is not easy to do but you can keep in mind that unless a very good reason, the team won't accept a new dependency to be added to the core.

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 as the dependency check is performed at runtime.

Perltidy

Tests

RELEASING

Public releases

Developer releases

Whenever the devel branch has been merged into the master branch, the CPAN release built must be a developer version (the version number should contain 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 brings regressions.

Roadmap

The next major release is Dancer 1.2, all of the following items must be completed before this version is released.

AUTHOR

This document has been written by Alexis Sukrieh sukria@cpan.org