1Dancer::Development(3)User Contributed Perl DocumentationDancer::Development(3)
2
3
4

NAME

6       Dancer::Development - guide for developers interested in contributing
7

VERSION

9       version 1.3513
10

DESCRIPTION

12       This guide has been written to help anyone interested in contributing
13       to the development of Dancer.
14
15       First of all - thank you for your interest in the project!  It's the
16       community of helpful contributors who've helped Dancer experience
17       phenomenal growth to get to where it is today.
18
19       Please read this guide before contributing to Dancer, to avoid wasted
20       effort and maximizing the chances of your contributions being used.
21

WAYS TO CONTRIBUTE

23       There are many ways to contribute to the project. Dancer is a young yet
24       active project and any kind of help is very much appreciated!
25
26   Publicity
27       You don't have to start by hacking the code, spreading the word is very
28       valuable as well!
29
30       If you have a blog, just feel free to speak about Dancer.
31
32       If you're a Twitter user, you can tweet about it with the hashtag
33       "#perl" (and feel free to follow @PerlDancer for news and updates on
34       Dancer!).
35
36       Of course, it doesn't have to be limited to blogs or Twitter.  Feel
37       free to spread the word in whatever way you consider fit and drop us a
38       line on the Dancer user mailing list noted below.
39
40       Also, if you're using and enjoying Dancer, rating us on
41       cpanratings.perl.org <http://cpanratings.perl.org/dist/Dancer>,
42       explaining what you like about Dancer is another very valuable
43       contribution that helps other new users find us!
44
45   Mailing list / IRC community
46       Subscribing to the mailing list and/or hanging out on our IRC channel
47       and providing assistance to new users is incredibly valuable.
48
49       •   Mailing list:
50           <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users> to
51           subscribe or view archives
52
53       •   IRC: "#dancer" on "irc.perl.org", or
54           <http://www.perldancer.org/irc> for a quick web client.
55
56   Documentation
57       While we value documentation very much, it's difficult to keep it up-
58       to-date.  If you find a typo or an error in the documentation please do
59       let us know - ideally by submitting a patch with your fix (see "Patch
60       Submission").
61
62   Contribute to CPAN Testers
63       If you have access to perl on rare operating systems, please consider
64       contributing tests. See
65       <http://wiki.cpantesters.org/wiki/TestDuringInstall> for more
66       information.
67
68   Code
69       You can write extensions (plugins) for Dancer extending Dancer's core
70       functionality or contribute to Dancer's core code, see "Patch
71       Submission" below.
72

GENERAL DEVELOPMENT GUIDELINES

74       This section lists high-level recommendations for developing Dancer,
75       for more detailed guidelines, see "Coding Guidelines" below.
76
77   Quality Assurance
78       Dancer should be able to install for all Perl versions since 5.8, on
79       any platform for which Perl exists. We focus mainly on GNU/Linux (any
80       distribution), *BSD and Windows (native and Cygwin).
81
82       We should avoid regressions as much as possible and keep backwards
83       compatibility in mind when refactoring. Stable releases should not
84       break functionality and new releases should provide an upgrade path and
85       upgrade tips such as warning the user about deprecated functionality.
86
87   Quality Supervision
88       We can measure our quality using the CPAN testers platform:
89       <http://www.cpantesters.org>.
90
91       A good way to help the project is to find a failing build log on the
92       CPAN testers: <http://www.cpantesters.org/distro/D/Dancer.html>
93
94       If you find a failing test report, feel free to report it as a GitHub
95       issue: <https://github.com/PerlDancer/Dancer/issues>.
96
97   Reporting Bugs
98       We prefer to have all our bug reports on GitHub, in the issues section:
99       <https://github.com/PerlDancer/Dancer/issues>. It's possible though to
100       report bugs on RT as well:
101       <https://rt.cpan.org/Dist/Display.html?Queue=Dancer>
102
103       Please make sure the bug you're reporting does not yet exist. In doubt
104       please ask on IRC.
105
106   Patch Submission
107       The Dancer development team uses GitHub to collaborate.  We greatly
108       appreciate contributions submitted via GitHub, as it makes tracking
109       these contributions and applying them much, much easier. This gives
110       your contribution a much better chance of being integrated into Dancer
111       quickly!
112
113       To help us achieve high-quality, stable releases, git-flow workflow is
114       used to handle pull-requests, that means contributors must work on
115       their "devel" branch rather than on their "master".  (Master should be
116       touched only by the core dev team when preparing a release to CPAN; all
117       ongoing development happens in branches which are merged to the "devel"
118       branch.)
119
120       Here is the workflow for submitting a patch:
121
122       •   Fork the repository <https://github.com/PerlDancer/Dancer> (click
123           "Fork")
124
125       •   Clone your fork to have a local copy using the following command:
126
127               $ git clone git://github.com/myname/Dancer.git
128
129       •   As a contributor, you should always work on the "devel" branch of
130           your clone ("master" is used only for building releases).
131
132               $ git remote add upstream https://github.com/PerlDancer/Dancer.git
133               $ git fetch upstream
134               $ git checkout -b devel upstream/devel
135
136           This will create a local branch in your clone named "devel" and
137           that will track the official "devel" branch. That way, if you have
138           more or less commits than the upstream repo, you'll be immediately
139           notified by git.
140
141       •   You want to isolate all your commits in a topic branch, this will
142           make the reviewing much easier for the core team and will allow you
143           to continue working on your clone without worrying about different
144           commits mixing together.
145
146           To do that, first create a local branch to build your pull request:
147
148               # you should be in devel here
149               git checkout -b pr/$name
150
151           Now you have created a local branch named pr/$name where $name is
152           the name you want (it should describe the purpose of the pull
153           request you're preparing).
154
155           In that branch, do all the commits you need (the more the better)
156           and when done, push the branch to your fork:
157
158               # ... commits ...
159               git push origin pr/$name
160
161           You are now ready to send a pull request.
162
163       •   Send a pull request via the GitHub interface. Make sure your pull
164           request is based on the pr/$name branch you've just pushed, so that
165           it incorporates the appropriate commits only.
166
167           It's also a good idea to summarize your work in a report sent to
168           the users mailing list (see below), in order to make sure the team
169           is aware of it.
170
171           You could also notify the core team on IRC, on "irc.perl.org",
172           channel "#dancer" or <http://www.perldancer.org/irc>.
173
174       •   When the core team reviews your pull request, it will either accept
175           (and then merge into devel) or refuse your request.
176
177           If it's refused, try to understand the reasons explained by the
178           team for the denial. Most of the time, communicating with the core
179           team is enough to understand what the mistake was. Above all,
180           please don't be offended.
181
182           If your pull-request is merged into devel, then all you have to do
183           is to remove your local and remote pr/$name branch:
184
185               git checkout devel
186               git branch -D pr/$name
187               git push origin :pr/$name
188
189           And then, of course, you need to sync your local devel branch with
190           the upstream:
191
192               git pull upstream devel
193               git push origin devel
194
195           You're now ready to start working on a new pull request!
196

About the Release Cycle

198       Since version 1.2, the team has decided to take a step further toward
199       production concerns: Dancer now promises to provide an API-stable and
200       feature frozen release, whose updates will only be about bugfixes and
201       documentation updates.
202
203       After some discussion with the core-team members, it has been agreed
204       that the 1.2xx release series will be the first of this kind, and will
205       live as long as 1.3xx lives.
206
207       As soon as the last 1.3xx release is mature enough and the core team is
208       happy with, it will be uploaded as the first version of the 1.4xx
209       series, and 1.2xx will become obsolete.
210
211       This lets us evolve quickly in our main track (devel in GitHub will
212       contain all the daily work we want to make 1.3xx better) but as well,
213       it lets us assure maintainability for the 1.2 series, as we will
214       probably have to fix a bug somewhere in 1.2 without merging with new
215       stuff contained in the devel branch.
216
217       That's why a maintenance branch is added to the repo. To be very clear,
218       this branch is named "frozen", to reflect the idea that the source-code
219       in this branch is not meant to evolve regarding features.  It should
220       only contains fixes for bug or documentation updates.
221
222       If you want to submit a pull-request to the frozen branch (that means
223       1.3xx is out and you've found a bug in 1.2xx) you need to base your
224       work on the "frozen" branch. Use the same procedure explained before,
225       but with the "frozen" branch.
226

RESOURCES FOR DEVELOPERS

228   Mailing Lists
229       A mailing list is available here:
230       <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users>
231
232   IRC Channels
233       You can reach the development team on irc.perl.org, channel #dancer or
234       via a web chat interface at <http://www.perldancer.org/irc>.  We're
235       always happy to hear from users and contributors.
236
237   Repositories
238       The official repository is hosted on GitHub at the following location:
239       <https://github.com/PerlDancer/Dancer>.
240
241       Official developers have write access to this repository, contributors
242       are invited to fork it if they want to submit patches, as explained in
243       the Patch submission section.
244
245       The repository layout is organized as follows:
246
247       •   "master"
248
249           This branch is dedicated to prepare CPAN releases. We push to that
250           branch only for packaging a new release. Every CPAN version are
251           made from this branch.
252
253       •   "devel"
254
255           This is the development branch. New features are pushed here, and
256           will be merged to master when the next release is being prepared.
257
258       Working with the devel branch
259
260       The distribution is managed with Dist::Zilla.  This means than many of
261       the usual files you might expect are not in the repository, but are
262       generated at release time.
263
264       However, you can run tests directly using the 'prove' tool:
265
266           $ prove -l
267           $ prove -lv t/some_test_file.t
268           $ prove -lvr t/
269
270       In most cases, 'prove' is entirely sufficient for you to test any
271       patches you have.
272
273       You may need to satisfy some dependencies. The easiest way to satisfy
274       dependencies is to install the last release -- this is available at
275       <https://metacpan.org/release/Dancer>.
276
277       If you use cpanminus, you can do it without downloading the tarball
278       first:
279
280           $ cpanm --reinstall --installdeps --with-recommends Dancer
281
282       Dist::Zilla is a very powerful authoring tool, but requires a number of
283       author-specific plugins. If you would like to use it for contributing,
284       install it from CPAN, then run one of the following commands, depending
285       on your CPAN client:
286
287           # with cpanminus
288           $ dzil authordeps --missing | cpanm
289
290           # with  cpan
291           $ cpan `dzil authordeps --missing`
292
293       You should then also install any additional requirements not needed by
294       the dzil build but may be needed by tests or other development:
295
296           # with cpanminus
297           $ dzil listdeps --author --missing | cpanm
298
299           # or just plain cpan...
300           $ cpan `dzil listdeps --author --missing`
301
302       You can also do this via cpanm directly:
303
304           $ cpanm --reinstall --installdeps --with-develop --with-recommends Dancer
305
306       Once installed, here are some dzil commands you might try:
307
308       $ dzil build
309           Build the code as it would appears on the final release.  The
310           tarball of the new distribution will be present in the root
311           directory of the repository, and a called "build/<this_branch">,
312           where this_branch is the current working branch, will also have the
313           product of the dzillification of the code.
314
315       $ dzil test
316           Run all tests in /t against the built code.
317
318       $ dzil xtest
319           Run the author tests (in /xt) against the built code.
320
321       $ dzil listdeps --json
322           List all the dependencies, in JSON.
323
324       $ dzil build --notgz
325           Build the code, but don't generate the tarball.
326
327       This Is Complicated. Is There an Easier Way?
328
329       Actually, yes there is. You can also branch out directly from the
330       master branch, which corresponds to the code is generated by
331       Dist::Zilla and what is uploaded to CPAN. It won't contain any of the
332       changes brought to the codebase since the last CPAN release, but for a
333       small patch that shouldn't be a problem.
334

CODING GUIDELINES

336       This section describes standards and requirements for coding. For more
337       broad guidelines, see "GENERAL DEVELOPMENT GUIDELINES" above.
338
339   About Dependencies
340       Dancer is intended to be a micro-framework. That means among other
341       things that it should remain lightweight. For this reason we try very
342       hard to keep the dependencies as low as possible. On the other hand, we
343       don't want to reinvent the wheel either.
344
345       We not likely to accept a new dependency to the core unless there is a
346       very good reason.
347
348       If a patch provides a new feature that depends on a module, the
349       solution is to perform a dynamic loading. Dancer has a class dedicated
350       to that job: Dancer::ModuleLoader. Here is an example of how to use it:
351
352           package Dancer::Some::Thing;
353           use Carp;
354
355           sub init {
356               Dancer::ModuleLoader->load('Some::Deps')
357                   or croak "the feature provided by Dancer::Some::Thing needs Some::Deps";
358           }
359
360       That way, an optional feature doesn't block Dancer from being installed
361       since the dependency check is performed at runtime.
362
363   Perltidy
364   Tests

RELEASING

366   Public Releases
367       Public and stable releases are those without an underline ('_') in the
368       version number. The latest stable release can be downloaded from CPAN
369       and github.com.
370
371   Developer Releases
372       Developer releases are those which include an underline ('_') in the
373       version number. Whenever the devel branch has been merged into the
374       master branch, the CPAN release built must be a developer version (the
375       version number contains a '_').
376
377       Before a new release is made, the uploaders must wait for the CPAN
378       testers reports. This is done to make sure the new merge doesn't bring
379       regressions.
380
381   Roadmap
382       For current information on Dancer's plans for the future, see the file
383       TODO at <https://github.com/PerlDancer/Dancer/blob/master/TODO>.
384

AUTHOR

386       Dancer Core Developers
387
389       This software is copyright (c) 2010 by Alexis Sukrieh.
390
391       This is free software; you can redistribute it and/or modify it under
392       the same terms as the Perl 5 programming language system itself.
393
394
395
396perl v5.32.1                      2021-01-27            Dancer::Development(3)
Impressum