.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Dancer::Development 3pm" .TH Dancer::Development 3pm "2014-10-20" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dancer::Development \- guide for developers interested in contributing .SH "VERSION" .IX Header "VERSION" version 1.3132 .SH "DESCRIPTION" .IX Header "DESCRIPTION" This guide has been written to help anyone interested in contributing to the development of Dancer. .PP First of all \- thank you for your interest in the project! It's the community of helpful contributors who've helped Dancer experience phenomenal growth to get to where it is today. .PP Please read this guide before contributing to Dancer, to avoid wasted effort and maximizing the chances of your contributions being used. .SH "WAYS TO CONTRIBUTE" .IX Header "WAYS TO CONTRIBUTE" There are many ways to contribute to the project. Dancer is a young yet active project and any kind of help is very much appreciated! .SS "Publicity" .IX Subsection "Publicity" You don't have to start by hacking the code, spreading the word is very valuable as well! .PP If you have a blog, just feel free to speak about Dancer. .PP If you're a Twitter user, you can tweet about it with the hashtag \f(CW\*(C`#perl\*(C'\fR (and feel free to follow \f(CW@PerlDancer\fR for news and updates on Dancer!). .PP 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 Dancer user mailing list noted below. .PP Also, if you're using and enjoying Dancer, rating us on cpanratings.perl.org , explaining what you like about Dancer is another very valuable contribution that helps other new users find us! .SS "Mailing list / \s-1IRC\s0 community" .IX Subsection "Mailing list / IRC community" Subscribing to the mailing list and/or hanging out on our \s-1IRC\s0 channel and providing assistance to new users is incredibly valuable. .IP "\(bu" 4 Mailing list: to subscribe or view archives .IP "\(bu" 4 \&\s-1IRC: \s0\f(CW\*(C`#dancer\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR, or for a quick web client. .SS "Documentation" .IX Subsection "Documentation" 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 \*(L"Patch Submission\*(R"). .SS "Contribute to \s-1CPAN\s0 Testers" .IX Subsection "Contribute to CPAN Testers" If you have access to perl on rare operating systems, please consider contributing tests. See for more information. .SS "Code" .IX Subsection "Code" You can write extensions (plugins) for Dancer extending Dancer's core functionality or contribute to Dancer's core code, see \*(L"Patch Submission\*(R" below. .SH "GENERAL DEVELOPMENT GUIDELINES" .IX Header "GENERAL DEVELOPMENT GUIDELINES" This section lists high-level recommendations for developing Dancer, for more detailed guidelines, see \*(L"Coding Guidelines\*(R" below. .SS "Quality Assurance" .IX Subsection "Quality Assurance" 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). .PP 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. .SS "Quality Supervision" .IX Subsection "Quality Supervision" We can measure our quality using the \s-1CPAN\s0 testers platform: . .PP A good way to help the project is to find a failing build log on the \s-1CPAN\s0 testers: .PP If you find a failing test report, feel free to report it as a GitHub issue: . .SS "Reporting Bugs" .IX Subsection "Reporting Bugs" We prefer to have all our bug reports on GitHub, in the issues section: . It's possible though to report bugs on \s-1RT\s0 as well: .PP Please make sure the bug you're reporting does not yet exist. In doubt please ask on \s-1IRC.\s0 .SS "Patch Submission" .IX Subsection "Patch Submission" 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! .PP To help us achieve high-quality, stable releases, git-flow workflow is used to handle pull-requests, that means contributors must work on their \f(CW\*(C`devel\*(C'\fR branch rather than on their \f(CW\*(C`master\*(C'\fR. (Master should be touched only by the core dev team when preparing a release to \s-1CPAN\s0; all ongoing development happens in branches which are merged to the \f(CW\*(C`devel\*(C'\fR branch.) .PP Here is the workflow for submitting a patch: .IP "\(bu" 4 Fork the repository (click \*(L"Fork\*(R") .IP "\(bu" 4 Clone your fork to have a local copy using the following command: .Sp .Vb 1 \& $ git clone git://github.com/myname/Dancer.git .Ve .IP "\(bu" 4 As a contributor, you should \fBalways\fR work on the \f(CW\*(C`devel\*(C'\fR branch of your clone (\f(CW\*(C`master\*(C'\fR is used only for building releases). .Sp .Vb 3 \& $ git remote add upstream https://github.com/PerlDancer/Dancer.git \& $ git fetch upstream \& $ git checkout \-b devel upstream/devel .Ve .Sp This will create a local branch in your clone named \f(CW\*(C`devel\*(C'\fR and that will track the official \f(CW\*(C`devel\*(C'\fR branch. That way, if you have more or less commits than the upstream repo, you'll be immediately notified by git. .IP "\(bu" 4 You want to isolate all your commits in a \fItopic\fR 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. .Sp To do that, first create a local branch to build your pull request: .Sp .Vb 2 \& # you should be in devel here \& git checkout \-b pr/$name .Ve .Sp Now you have created a local branch named \fIpr/$name\fR where \fI\f(CI$name\fI\fR is the name you want (it should describe the purpose of the pull request you're preparing). .Sp In that branch, do all the commits you need (the more the better) and when done, push the branch to your fork: .Sp .Vb 2 \& # ... commits ... \& git push origin pr/$name .Ve .Sp You are now ready to send a pull request. .IP "\(bu" 4 Send a \fIpull request\fR via the GitHub interface. Make sure your pull request is based on the \fIpr/$name\fR branch you've just pushed, so that it incorporates the appropriate commits only. .Sp 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. .Sp You could also notify the core team on \s-1IRC,\s0 on \f(CW\*(C`irc.perl.org\*(C'\fR, channel \&\f(CW\*(C`#dancer\*(C'\fR or . .IP "\(bu" 4 When the core team reviews your pull request, it will either accept (and then merge into \fIdevel\fR) or refuse your request. .Sp 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. .Sp If your pull-request is merged into \fIdevel\fR, then all you have to do is to remove your local and remote \fIpr/$name\fR branch: .Sp .Vb 3 \& git checkout devel \& git branch \-D pr/$name \& git push origin :pr/$name .Ve .Sp And then, of course, you need to sync your local devel branch with the upstream: .Sp .Vb 2 \& git pull upstream devel \& git push origin devel .Ve .Sp You're now ready to start working on a new pull request! .SH "About the Release Cycle" .IX Header "About the Release 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. .PP 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. .PP As soon as the last 1.3xx release is mature enough and 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. .PP 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. .PP That's why a maintenance branch is added to the repo. To be very clear, this branch is named "\fIfrozen\fR", 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. .PP 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 \f(CW\*(C`frozen\*(C'\fR branch. Use the same procedure explained before, but with the \f(CW\*(C`frozen\*(C'\fR branch. .SH "RESOURCES FOR DEVELOPERS" .IX Header "RESOURCES FOR DEVELOPERS" .SS "Mailing Lists" .IX Subsection "Mailing Lists" A mailing list is available here: .SS "\s-1IRC\s0 Channels" .IX Subsection "IRC Channels" You can reach the development team on irc.perl.org, channel #dancer or via a web chat interface at . We're always happy to hear from users and contributors. .SS "Repositories" .IX Subsection "Repositories" The official repository is hosted on GitHub at the following location: . .PP Official developers have write access to this repository, contributors are invited to fork it if they want to submit patches, as explained in the \&\fIPatch submission\fR section. .PP The repository layout is organized as follows: .IP "\(bu" 4 \&\f(CW\*(C`master\*(C'\fR .Sp This branch is dedicated to prepare \s-1CPAN\s0 releases. We push to that branch only for packaging a new release. Every \s-1CPAN\s0 version are made from this branch. .IP "\(bu" 4 \&\f(CW\*(C`devel\*(C'\fR .Sp This is the development branch. New features are pushed here, and will be merged to master when the next release is being prepared. .SH "CODING GUIDELINES" .IX Header "CODING GUIDELINES" This section describes standards and requirements for coding. For more broad guidelines, see \*(L"\s-1GENERAL DEVELOPMENT GUIDELINES\*(R"\s0 above. .SS "About Dependencies" .IX Subsection "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. .PP We not likely to accept a new dependency to the core unless there is a very good reason. .PP 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: .PP .Vb 2 \& package Dancer::Some::Thing; \& use Carp; \& \& sub init { \& Dancer::ModuleLoader\->load(\*(AqSome::Deps\*(Aq) \& or croak "the feature provided by Dancer::Some::Thing needs Some::Deps"; \& } .Ve .PP That way, an optional feature doesn't block Dancer from being installed since the dependency check is performed at runtime. .SS "Perltidy" .IX Subsection "Perltidy" .SS "Tests" .IX Subsection "Tests" .SH "RELEASING" .IX Header "RELEASING" .SS "Public Releases" .IX Subsection "Public Releases" Public and stable releases are those without an underline ('_') in the version number. The latest stable release can be downloaded from \s-1CPAN\s0 and github.com. .SS "Developer Releases" .IX Subsection "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 \&\s-1CPAN\s0 release built must be a developer version (the version number contains a \&'_'). .PP Before a new release is made, the uploaders must wait for the \s-1CPAN\s0 testers reports. This is done to make sure the new merge doesn't bring regressions. .SS "Roadmap" .IX Subsection "Roadmap" For current information on Dancer's plans for the future, see the file \s-1TODO\s0 at . .SH "AUTHOR" .IX Header "AUTHOR" This document has been written by Alexis Sukrieh sukria@cpan.org .SH "AUTHOR" .IX Header "AUTHOR" Dancer Core Developers .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by Alexis Sukrieh. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.