From 8db94cb2c5c83e64be494dc820facb37bc5a3ad0 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:39:17 +0200 Subject: [PATCH 01/13] adding raw Migration from Snigdha --- lib/Dancer2/Migration.pod | 68 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 lib/Dancer2/Migration.pod diff --git a/lib/Dancer2/Migration.pod b/lib/Dancer2/Migration.pod new file mode 100644 index 000000000..ea776771f --- /dev/null +++ b/lib/Dancer2/Migration.pod @@ -0,0 +1,68 @@ +=pod + +=head2 Migration from Dancer1 to Dancer2 + +This document covers some changes that users will need to be aware of while upgrading from Dancer1 to Dancer2. + + +=head3 Apps + +1. In Dancer2, each module is a B with its own namespace and variables. You can set the application name in each of your Dancer2 application modules. Different modules can be tied into the same app by setting the application name to the same value. + +For example, to set the appname directive explicitly: + + package myapp; + use Dancer2; + use myapp::admin; + + hook before => sub { + var db => "..."; + }; + + prefix undef; + get '/' => sub {...}; + + 1; + + package myapp::admin; + use Dancer2 appname => "myapp"; + + prefix '/admin'; + get '/' => sub {...}; + + 1; + +Without the appname directive, C would not have access to C. In fact, when accessing C, the before hook would not be executed. +See L for details. + +2. The following modules can be used to speed up an app in Dancer2 : + +L + +L + +L + +They would need to be installed separately. This is because Dancer2 does not incorporate any C code, but it can get C-code compiled as a module. +Thus, these modules can be used for speed improvement provided: + +i) You have access to a C interpreter + +ii) You don't need to fatpack your application + +=head3 Plugins: plugin_setting + +B returns the configuration of the plugin. It can no longer be called outside of C or C. + +=head3 Routes + +Dancer2 requires all routes defined via a string to begin with a leading slash C. + +For example: + + get '0' => sub { + return "not gonna fly"; + }; + +would return an error. The correct way to write this would be to use C + From 905ed0b7a521b393684fbf36b62b168187a20816 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:40:56 +0200 Subject: [PATCH 02/13] break at column 80 --- lib/Dancer2/Migration.pod | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/lib/Dancer2/Migration.pod b/lib/Dancer2/Migration.pod index ea776771f..e4efb8685 100644 --- a/lib/Dancer2/Migration.pod +++ b/lib/Dancer2/Migration.pod @@ -2,12 +2,16 @@ =head2 Migration from Dancer1 to Dancer2 -This document covers some changes that users will need to be aware of while upgrading from Dancer1 to Dancer2. +This document covers some changes that users will need to be aware of +while upgrading from Dancer1 to Dancer2. =head3 Apps -1. In Dancer2, each module is a B with its own namespace and variables. You can set the application name in each of your Dancer2 application modules. Different modules can be tied into the same app by setting the application name to the same value. +1. In Dancer2, each module is a B with its own +namespace and variables. You can set the application name in each of your +Dancer2 application modules. Different modules can be tied into the same +app by setting the application name to the same value. For example, to set the appname directive explicitly: @@ -32,8 +36,12 @@ For example, to set the appname directive explicitly: 1; -Without the appname directive, C would not have access to C. In fact, when accessing C, the before hook would not be executed. -See L for details. +Without the appname directive, C would not have access +to C. In fact, when accessing C, the before hook would +not be executed. + +See L +for details. 2. The following modules can be used to speed up an app in Dancer2 : @@ -43,7 +51,8 @@ L L -They would need to be installed separately. This is because Dancer2 does not incorporate any C code, but it can get C-code compiled as a module. +They would need to be installed separately. This is because Dancer2 does +not incorporate any C code, but it can get C-code compiled as a module. Thus, these modules can be used for speed improvement provided: i) You have access to a C interpreter @@ -52,11 +61,13 @@ ii) You don't need to fatpack your application =head3 Plugins: plugin_setting -B returns the configuration of the plugin. It can no longer be called outside of C or C. +B returns the configuration of the plugin. It can no +longer be called outside of C or C. =head3 Routes -Dancer2 requires all routes defined via a string to begin with a leading slash C. +Dancer2 requires all routes defined via a string to begin with a leading +slash C. For example: @@ -64,5 +75,6 @@ For example: return "not gonna fly"; }; -would return an error. The correct way to write this would be to use C +would return an error. The correct way to write this would be to use +C From 1cbff8a4e5b5d6f0bb009a25991d3dcfc82e04a8 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:41:51 +0200 Subject: [PATCH 03/13] namespace it --- lib/Dancer2/{ => Manual}/Migration.pod | 9 +++++++++ 1 file changed, 9 insertions(+) rename lib/Dancer2/{ => Manual}/Migration.pod (96%) diff --git a/lib/Dancer2/Migration.pod b/lib/Dancer2/Manual/Migration.pod similarity index 96% rename from lib/Dancer2/Migration.pod rename to lib/Dancer2/Manual/Migration.pod index e4efb8685..61b4f002d 100644 --- a/lib/Dancer2/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -1,3 +1,12 @@ +package Dancer2::Manual::Migration; + +use strict; +use warnings; + +1; + +__END__ + =pod =head2 Migration from Dancer1 to Dancer2 From 2ea7ad9b7160386ac3e2932c77d84179d2d3dd91 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:44:20 +0200 Subject: [PATCH 04/13] spacing for code --- lib/Dancer2/Manual/Migration.pod | 34 ++++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index 61b4f002d..c77eb3198 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -24,26 +24,26 @@ app by setting the application name to the same value. For example, to set the appname directive explicitly: - package myapp; - use Dancer2; - use myapp::admin; + package myapp; + use Dancer2; + use myapp::admin; - hook before => sub { - var db => "..."; - }; + hook before => sub { + var db => "..."; + }; - prefix undef; - get '/' => sub {...}; + prefix undef; + get '/' => sub {...}; - 1; + 1; - package myapp::admin; - use Dancer2 appname => "myapp"; + package myapp::admin; + use Dancer2 appname => "myapp"; - prefix '/admin'; - get '/' => sub {...}; + prefix '/admin'; + get '/' => sub {...}; - 1; + 1; Without the appname directive, C would not have access to C. In fact, when accessing C, the before hook would @@ -80,9 +80,9 @@ slash C. For example: - get '0' => sub { - return "not gonna fly"; - }; + get '0' => sub { + return "not gonna fly"; + }; would return an error. The correct way to write this would be to use C From 2c4adb60c7e7be4c85ffb584e28a067e9248781c Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:45:52 +0200 Subject: [PATCH 05/13] itemize --- lib/Dancer2/Manual/Migration.pod | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index c77eb3198..839ea5f32 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -14,7 +14,6 @@ __END__ This document covers some changes that users will need to be aware of while upgrading from Dancer1 to Dancer2. - =head3 Apps 1. In Dancer2, each module is a B with its own @@ -52,21 +51,29 @@ not be executed. See L for details. -2. The following modules can be used to speed up an app in Dancer2 : +2. The following modules can be used to speed up an app in Dancer2: + +=over 4 + +=item * L -L +=item * L -L +=item * L -L +=back They would need to be installed separately. This is because Dancer2 does not incorporate any C code, but it can get C-code compiled as a module. Thus, these modules can be used for speed improvement provided: -i) You have access to a C interpreter +=over 4 + +=item * You have access to a C interpreter + +=item * You don't need to fatpack your application -ii) You don't need to fatpack your application +=back =head3 Plugins: plugin_setting From abb9ce5c9b0233638e074f256d2491725ea043c9 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:46:52 +0200 Subject: [PATCH 06/13] links already default to the website its on --- lib/Dancer2/Manual/Migration.pod | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index 839ea5f32..fd8f2c949 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -55,11 +55,11 @@ for details. =over 4 -=item * L +=item * L -=item * L +=item * L -=item * L +=item * L =back From 126863c43829e3aa6f6439358adbc6d68973254d Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:48:52 +0200 Subject: [PATCH 07/13] linkify --- lib/Dancer2/Manual/Migration.pod | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index fd8f2c949..a3f152f5c 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -12,13 +12,13 @@ __END__ =head2 Migration from Dancer1 to Dancer2 This document covers some changes that users will need to be aware of -while upgrading from Dancer1 to Dancer2. +while upgrading from L (version 1) to L. =head3 Apps -1. In Dancer2, each module is a B with its own +1. In L, each module is a B with its own namespace and variables. You can set the application name in each of your -Dancer2 application modules. Different modules can be tied into the same +L application modules. Different modules can be tied into the same app by setting the application name to the same value. For example, to set the appname directive explicitly: @@ -63,7 +63,7 @@ for details. =back -They would need to be installed separately. This is because Dancer2 does +They would need to be installed separately. This is because L does not incorporate any C code, but it can get C-code compiled as a module. Thus, these modules can be used for speed improvement provided: @@ -82,7 +82,7 @@ longer be called outside of C or C. =head3 Routes -Dancer2 requires all routes defined via a string to begin with a leading +L requires all routes defined via a string to begin with a leading slash C. For example: From 3b2b0fa5c5869e058bd6a6c63cf39d1536609463 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:54:25 +0200 Subject: [PATCH 08/13] proper package names, reduce confusion in prefix --- lib/Dancer2/Manual/Migration.pod | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index a3f152f5c..96f4c9309 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -23,29 +23,34 @@ app by setting the application name to the same value. For example, to set the appname directive explicitly: - package myapp; +C: + + package MyApp; use Dancer2; - use myapp::admin; + use MyApp::Admin hook before => sub { - var db => "..."; + var db => 'Users'; }; - prefix undef; get '/' => sub {...}; 1; - package myapp::admin; - use Dancer2 appname => "myapp"; +C: - prefix '/admin'; - get '/' => sub {...}; + package MyApp::Admin; + use Dancer2 appname => 'MyApp'; + + # use a lexical prefix so we don't override it globally + prefix '/admin' => sub { + get '/' => sub {...}; + }; 1; -Without the appname directive, C would not have access -to C. In fact, when accessing C, the before hook would +Without the appname directive, C would not have access +to variable C. In fact, when accessing C, the before hook would not be executed. See L From 106b5872138cbaa0278f09d0cfbdc88b29c0065b Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Tue, 30 Sep 2014 00:54:40 +0200 Subject: [PATCH 09/13] use proper Pod tag for code --- lib/Dancer2/Manual/Migration.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index 96f4c9309..13b73abfb 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -82,7 +82,7 @@ Thus, these modules can be used for speed improvement provided: =head3 Plugins: plugin_setting -B returns the configuration of the plugin. It can no +C returns the configuration of the plugin. It can no longer be called outside of C or C. =head3 Routes From 001e0dd6fbed57c2c1527e0a57956caaa137a831 Mon Sep 17 00:00:00 2001 From: snigdha Date: Mon, 6 Oct 2014 03:20:43 +0530 Subject: [PATCH 10/13] Updated Migration.pod Added the clause on Tests --- lib/Dancer2/Manual/Migration.pod | 81 ++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index 13b73abfb..3056fed07 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -99,3 +99,84 @@ For example: would return an error. The correct way to write this would be to use C +=head3 Tests + +Dancer2 recommends the use of L. + +For example: + + use strict; + use warnings; + + use Test::More tests => 3; + + use Plack::Test; + use HTTP::Request::Common; + + use Test2; + { package Test2; set apphandler => 'PSGI'; set log => 'error'; } + + test_psgi( Test2::dance, sub { + my $app = shift; + + my $res = $app->( GET '/' ); + + ok $res->is_success; + + is $res->code => 200, 'response status is 200 for /'; + + like $res->content => qr#Test2#, 'title is okay'; + } ); + +Other modules that could be used for testing are: + +=over 4 + +=item * L + +=item * L + +=back + +=head4 Logs + +C can no longer be used, as with L. Instead, +L could be used for testing, to capture all +logs to an object. + +For example: + + use strict; + use warnings; + use Test::More import => ['!pass']; + use Plack::Test; + use HTTP::Request::Common; + + { + package App; + use Dancer2; + + set log => 'debug'; + set logger => 'capture'; + + get '/' => sub { + debug 'this is my debug message'; + return 1; + }; + } + + my $app = Dancer2->psgi_app; + is( ref $app, 'CODE', 'Got app' ); + + test_psgi $app, sub { + my $cb = shift; + + my $res = $cb->( GET '/' ); + is $res->code, 200; + + my $trap = App->dancer_app->logger_engine->trapper; + + is_deeply $trap->read, [ + { level => 'debug', message => 'this is my debug message' } + ]; + }; From 375df2b01cd5d29177f1c7a2d1400c35b86175f9 Mon Sep 17 00:00:00 2001 From: snigdha Date: Wed, 8 Oct 2014 23:10:00 +0530 Subject: [PATCH 11/13] clause on export tags added As of now, I have only mentioned the uses of plackup command, but not written anything about how things were done in Dancer1. Let me know me if the clause needs to be more descriptive or verbose. --- lib/Dancer2/Manual/Migration.pod | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index 3056fed07..111ce13a4 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -180,3 +180,14 @@ For example: { level => 'debug', message => 'this is my debug message' } ]; }; + +=head3 Exports: Tags + +The following tags are not needed in L: + + use Dancer2 qw(:syntax); + use Dancer2 qw(:tests); + use Dancer2 qw(:script); + +The C command should be used instead. It provides a development +server and reads the configuration options in your command line utilities. From 0a0c01d67f92ff2de48226f38c22628472d5b968 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Wed, 8 Oct 2014 21:21:00 +0200 Subject: [PATCH 12/13] remove extra spacing --- lib/Dancer2/Manual/Migration.pod | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/lib/Dancer2/Manual/Migration.pod b/lib/Dancer2/Manual/Migration.pod index 111ce13a4..3243ce2b6 100644 --- a/lib/Dancer2/Manual/Migration.pod +++ b/lib/Dancer2/Manual/Migration.pod @@ -90,7 +90,7 @@ longer be called outside of C or C. L requires all routes defined via a string to begin with a leading slash C. -For example: +For example: get '0' => sub { return "not gonna fly"; @@ -101,10 +101,10 @@ C =head3 Tests -Dancer2 recommends the use of L. +Dancer2 recommends the use of L. For example: - + use strict; use warnings; @@ -127,12 +127,12 @@ For example: like $res->content => qr#Test2#, 'title is okay'; } ); - -Other modules that could be used for testing are: + +Other modules that could be used for testing are: =over 4 -=item * L +=item * L =item * L @@ -140,9 +140,9 @@ Other modules that could be used for testing are: =head4 Logs -C can no longer be used, as with L. Instead, -L could be used for testing, to capture all -logs to an object. +C can no longer be used, as with L. Instead, +L could be used for testing, to capture all +logs to an object. For example: @@ -190,4 +190,4 @@ The following tags are not needed in L: use Dancer2 qw(:script); The C command should be used instead. It provides a development -server and reads the configuration options in your command line utilities. +server and reads the configuration options in your command line utilities. From 627cf2f557e2008422c3208083a4e74512138f13 Mon Sep 17 00:00:00 2001 From: Sawyer X Date: Wed, 8 Oct 2014 21:22:37 +0200 Subject: [PATCH 13/13] reflect changes --- Changes | 1 + 1 file changed, 1 insertion(+) diff --git a/Changes b/Changes index d99a86bfb..e43286305 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,7 @@ {{$NEXT}} [ DOCUMENTATION ] + * Migration document! (Snigdha Dagar) * GH #667: Fix typo in cookbook pod. (Lindsey Beesley) * GH #649, #670: Document core logger. (simbabque) * GH #689: Git guide markdown fixes. (Paul Cochrane)