1Dancer::Development(3)User Contributed Perl DocumentationDancer::Development(3)
2
6 Dancer::Development - guide for developers interested in contributing
7
9 version 1.3513
10
12 This guide has been written to help anyone interested in contributing
13 to the development of Dancer.
14 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 Please read this guide before contributing to Dancer, to avoid wasted
20 effort and maximizing the chances of your contributions being used.
21
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 Publicity
27 You don't have to start by hacking the code, spreading the word is very
28 valuable as well!
29 If you have a blog, just feel free to speak about Dancer.
31 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 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 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 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 • Mailing list:
50 <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users> to
51 subscribe or view archives
52 • IRC: "#dancer" on "irc.perl.org", or
54 <http://www.perldancer.org/irc> for a quick web client.
55 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 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 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
74 This section lists high-level recommendations for developing Dancer,
75 for more detailed guidelines, see "Coding Guidelines" below.
76 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 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 Quality Supervision
88 We can measure our quality using the CPAN testers platform:
89 <http://www.cpantesters.org>.
90 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 If you find a failing test report, feel free to report it as a GitHub
95 issue: <https://github.com/PerlDancer/Dancer/issues>.
96 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 Please make sure the bug you're reporting does not yet exist. In doubt
104 please ask on IRC.
105 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 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 Here is the workflow for submitting a patch:
121 • Fork the repository <https://github.com/PerlDancer/Dancer> (click
123 "Fork")
124 • Clone your fork to have a local copy using the following command:
126 $ git clone git://github.com/myname/Dancer.git
128 • As a contributor, you should always work on the "devel" branch of
130 your clone ("master" is used only for building releases).
131 $ git remote add upstream https://github.com/PerlDancer/Dancer.git
133 $ git fetch upstream
134 $ git checkout -b devel upstream/devel
135 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 • 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 To do that, first create a local branch to build your pull request:
147 # you should be in devel here
149 git checkout -b pr/$name
150 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 In that branch, do all the commits you need (the more the better)
156 and when done, push the branch to your fork:
157 # ... commits ...
159 git push origin pr/$name
160 You are now ready to send a pull request.
162 • 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 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 You could also notify the core team on IRC, on "irc.perl.org",
172 channel "#dancer" or <http://www.perldancer.org/irc>.
173 • When the core team reviews your pull request, it will either accept
175 (and then merge into devel) or refuse your request.
176 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 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 git checkout devel
186 git branch -D pr/$name
187 git push origin :pr/$name
188 And then, of course, you need to sync your local devel branch with
190 the upstream:
191 git pull upstream devel
193 git push origin devel
194 You're now ready to start working on a new pull request!
196
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 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 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 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 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 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
228 Mailing Lists
229 A mailing list is available here:
230 <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users>
231 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 Repositories
238 The official repository is hosted on GitHub at the following location:
239 <https://github.com/PerlDancer/Dancer>.
240 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 The repository layout is organized as follows:
246 • "master"
248 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 • "devel"
254 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 Working with the devel branch
259 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 However, you can run tests directly using the 'prove' tool:
265 $ prove -l
267 $ prove -lv t/some_test_file.t
268 $ prove -lvr t/
269 In most cases, 'prove' is entirely sufficient for you to test any
271 patches you have.
272 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 If you use cpanminus, you can do it without downloading the tarball
278 first:
279 $ cpanm --reinstall --installdeps --with-recommends Dancer
281 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 # with cpanminus
288 $ dzil authordeps --missing | cpanm
289 # with cpan
291 $ cpan `dzil authordeps --missing`
292 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 # with cpanminus
297 $ dzil listdeps --author --missing | cpanm
298 # or just plain cpan...
300 $ cpan `dzil listdeps --author --missing`
301 You can also do this via cpanm directly:
303 $ cpanm --reinstall --installdeps --with-develop --with-recommends Dancer
305 Once installed, here are some dzil commands you might try:
307 $ 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 $ dzil test
316 Run all tests in /t against the built code.
317 $ dzil xtest
319 Run the author tests (in /xt) against the built code.
320 $ dzil listdeps --json
322 List all the dependencies, in JSON.
323 $ dzil build --notgz
325 Build the code, but don't generate the tarball.
326 This Is Complicated. Is There an Easier Way?
328 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
336 This section describes standards and requirements for coding. For more
337 broad guidelines, see "GENERAL DEVELOPMENT GUIDELINES" above.
338 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 We not likely to accept a new dependency to the core unless there is a
346 very good reason.
347 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 package Dancer::Some::Thing;
353 use Carp;
354 sub init {
356 Dancer::ModuleLoader->load('Some::Deps')
357 or croak "the feature provided by Dancer::Some::Thing needs Some::Deps";
358 }
359 That way, an optional feature doesn't block Dancer from being installed
361 since the dependency check is performed at runtime.
362 Perltidy
364 Tests
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 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 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 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
386 Dancer Core Developers
387
389 This software is copyright (c) 2010 by Alexis Sukrieh.
390 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.
393perl v5.32.1 2021-01-27 Dancer::Development(3)