Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Dancer::Development(3)User Contributed Perl DocumentatioDancer::Development(3)

NAME
       Dancer::Development - guide for developers interested in	contributing

VERSION
       version 1.3513

DESCRIPTION
       This guide has been written to help anyone interested in	contributing
       to the development of Dancer.

       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.

       Please read this	guide before contributing to Dancer, to	avoid wasted
       effort and maximizing the chances of your contributions being used.

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!

   Publicity
       You don't have to start by hacking the code, spreading the word is very
       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" (and feel free to follow	@PerlDancer for	news and updates on
       Dancer!).

       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.

       Also, if	you're using and enjoying Dancer, rating us on
       cpanratings.perl.org <http://cpanratings.perl.org/dist/Dancer>,
       explaining what you like	about Dancer is	another	very valuable
       contribution that helps other new users find us!

   Mailing list	/ IRC community
       Subscribing to the mailing list and/or hanging out on our IRC channel
       and providing assistance	to new users is	incredibly valuable.

       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.

   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 "Patch
       Submission").

   Contribute to CPAN Testers
       If you have access to perl on rare operating systems, please consider
       contributing tests. See
       <http://wiki.cpantesters.org/wiki/TestDuringInstall> for	more
       information.

   Code
       You can write extensions	(plugins) for Dancer extending Dancer's	core
       functionality or	contribute to Dancer's core code, see "Patch
       Submission" below.

GENERAL	DEVELOPMENT GUIDELINES
       This section lists high-level recommendations for developing Dancer,
       for more	detailed guidelines, see "Coding Guidelines" below.

   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).

       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.

   Quality Supervision
       We can measure our quality using	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: <https://github.com/PerlDancer/Dancer/issues>.

   Reporting Bugs
       We prefer to have all our bug reports on	GitHub,	in the issues section:
       <https://github.com/PerlDancer/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 does not yet exist. In	doubt
       please ask on IRC.

   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!

       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	always 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,	you'll 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 you're 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 you've just pushed, so that
	   it incorporates the appropriate commits only.

	   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.

	   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 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.

	   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 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.

       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.

       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.

       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.

       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 procedure explained before,
       but with	the "frozen" branch.

RESOURCES FOR DEVELOPERS
   Mailing Lists
       A mailing list is available here:
       <http://lists.preshweb.co.uk/mailman/listinfo/dancer-users>

   IRC Channels
       You can reach the development team on irc.perl.org, channel #dancer or
       via a web chat interface	at <http://www.perldancer.org/irc>.  We're
       always happy to hear from users and contributors.

   Repositories
       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:

       o   "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.

       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.

       Working with the	devel branch

       The distribution	is managed with	Dist::Zilla.  This means than many of
       the usual files you might expect	are not	in the repository, but are
       generated at release time.

       However,	you can	run tests directly using the 'prove' tool:

	   $ prove -l
	   $ prove -lv t/some_test_file.t
	   $ prove -lvr	t/

       In most cases, 'prove' is entirely sufficient for you to	test any
       patches you have.

       You may need to satisfy some dependencies. The easiest way to satisfy
       dependencies is to install the last release -- this is available	at
       <https://metacpan.org/release/Dancer>.

       If you use cpanminus, you can do	it without downloading the tarball
       first:

	   $ cpanm --reinstall --installdeps --with-recommends Dancer

       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:

	   # with cpanminus
	   $ dzil authordeps --missing | cpanm

	   # with  cpan
	   $ cpan `dzil	authordeps --missing`

       You should then also install any	additional requirements	not needed by
       the dzil	build but may be needed	by tests or other development:

	   # with cpanminus
	   $ dzil listdeps --author --missing |	cpanm

	   # or	just plain cpan...
	   $ cpan `dzil	listdeps --author --missing`

       You can also do this via	cpanm directly:

	   $ cpanm --reinstall --installdeps --with-develop --with-recommends Dancer

       Once installed, here are	some dzil commands you might try:

       $ 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 don't generate the tarball.

       This Is Complicated. Is There an	Easier Way?

       Actually, yes there is. You can also branch out directly	from the
       master branch, which corresponds	to the code is generated by
       Dist::Zilla and what is uploaded	to CPAN. It won't contain any of the
       changes brought to the codebase since the last CPAN release, but	for a
       small patch that	shouldn't be a problem.

CODING GUIDELINES
       This section describes standards	and requirements for coding. For more
       broad guidelines, see "GENERAL DEVELOPMENT GUIDELINES" above.

   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.

       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:

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

   Perltidy
   Tests
RELEASING
   Public Releases
       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
       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 '_').

       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	bring
       regressions.

   Roadmap
       For current information on Dancer's plans for the future, see the file
       TODO at <https://github.com/PerlDancer/Dancer/blob/master/TODO>.

AUTHOR
       Dancer Core Developers

COPYRIGHT AND LICENSE
       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.32.1			  2020-01-29		Dancer::Development(3)

NAME | VERSION | DESCRIPTION | WAYS TO CONTRIBUTE | GENERAL DEVELOPMENT GUIDELINES | About the Release Cycle | RESOURCES FOR DEVELOPERS | CODING GUIDELINES | RELEASING | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Dancer::Development&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help