Add Dancer2::Manual::Migration

[racke]

We need migration docs for moving Dancer apps, plugins and engines from Dancer1 to Dancer2.

Please dump all information into this issue, I'll compile it in a POD later.

Regards
Racke

[racke]

forward instead of request->path_info in before hook.

[racke]

Commandline options (#471).

[xsawyerx]

• No middleware support. (use Plack::Builder instead)
• Use Test::Plack, not Test::TCP, LWP::Protocol::PSGI, or Dancer2::Test.

[xsawyerx]

Speeding up your app in D2:

• URL::Encode::XS
• CGI::Deurl::XS
• HTTP::Parser::XS

[xsawyerx]

Additional change:

• Routes are required to have a leading /. (see: Routes must have leading slash #581)
• (soon) Prefixes will not be allowed to have a postfix /. (see: Prefixes should not allow trailing slashes #593)

[shumphrey]

hooks are now app specific not global

[xsawyerx]

• No need for ':syntax' anymore

[racke]

before hook is fired even on files in public - that might be a bug!?

[jacqueslareau]

[% if settings.environment == "development" %]

Was working in Dancer1, not anymore.

[xsawyerx]

Those might be bugs though. Let's open "question" issues for them.

[jacqueslareau]

• A note on how engines (session, logger) configuration changed.
• Dancer2::Session::DBI and Dancer2::Plugin::Auth::Extensible are not available yet.
• hooks are not global anymore.
• Cannot seem to find any information on "use Dancer2 appname => 'MyApp';" as a patch.
• :script ?
• behind_proxy: just wanted to point out that it's not clear if behind_proxy replaces ReverseProxy, or if both can be used together or not

[xsawyerx]

Adding a new comment for each one of those makes it harder to track. I'm going to post a comment now answering some of them and tomorrow (hopefully morning) I will go over and merge the issues into the original comment so we could track it more easily.

• Plugins are not core. We're tracking changes in Dancer core itself. While it's good to know that Dancer2::Plugin::DBIC changed its key (and I agree it should not have, or at least should support both keys), it's not something that should be fixed in Dancer2 core, because it's not in core to begin with. It's a third-party module. You also opened a separate issue on it. We can't fix it, only the author of the module can. I will close that issue tomorrow.
• The behind_proxy comment is too vague. Please expand.
• Plugins are, again, not part of core. It's not that Dancer2::Session::DBI and Dancer2::Plugin::Auth::Extensible are not available in Dancer2. They aren't in Dancer1 either. It's that those plugins don't exist. Again, that's not up to us to fix.
• hooks do no need to be global. They are app-dependent. I'm happy you noted that because it's important, but I want to address your comment on "I don't have a clue how to make a global hook anymore": you don't need to. "Global hooks" are actually App-dependent hooks. You can then merge Apps under a common appname.
• :script is not needed. :syntax is not needed. @racke covered that above. Please review.

That's a start. Tomorrow I'm cleaning these comments and merging them in.

I would really appreciate it if, when you get another fantastic (not being cynical here) burst of "let's document these changes", please write a single comment with everything instead of 8 (I counted) different small one-line comments.

Again, we appreciate it. Thank you. :)

[jacqueslareau]

Sorry about all the comments. Please merge.

It's a burst because I just migrated the first of my many Dancer1 app and documented problems I encountered.

I clearly understand that plugins aren't in Dancer core. But they are major elements of the Dancer ecosystem. I may have misunderstood @racke when he wrote " moving Dancer apps, plugins ". He probably meant a guide for plugin devs to upgrade. I'm writing all of this as a Dancer user, not a core dev. So from my point of view, having this information at least somewhere (at least as a link to a blog post) would have saved me time.

• As for :script, I don't see a reference to it. I understand it, just wanted to point it out for the manual.
• DBIC: I opened the issue in the DBIC repo, not Dancer.
• behind_proxy: just wanted to point out that it's not clear if behind_proxy replaces ReverseProxy, or if both can be used together or not. Again, it's coming from a user.

Keep up the good work. I'm a big fan.

[xsawyerx]

Your input on this is super critical. Honestly this is the best we could have hoped for - having a user move their app, see what happen, and document it.

Our intention with plugins is to:

• Notify the authors
• Help them out (like starting to provide pull requests)
• Make necessary shims (like the last dev release will do for the previous ones) to help ease them in
• Help out with actual releases if they stall

This might possibly even extend to "port the plugin to this version" because the author might not. My point was merely to realize this is not part of core, but part of the core team wanting to make this transition more feasable. I suppose documenting this as "a change you might expect with Dancer2", rather than "this is what changed in Dancer2" is practical. I apologize for jumping the gun.

:script was meant to help write one-liners that call the app, and the app would parse the command line options. This is not just unnecessary (because plackup covers all those that were needed) but added additional maintenance and unknown behavior for those that haven't known this feature. We currently do not die or warn on it, to - again - make it an easier transition. At some point we will.

As for DBIC, my bad! Thanks. :)

Regarding behind_proxy: that is a very good comment. We'll need to make that clear. We're also not certain yet what we'll do with it.

Thanks again!

[racke]

On 08/07/2014 12:37 AM, Jacques Lareau wrote:

Plugin Dancer2::Plugin::DBIC
In Dancer1, 'password' was a valid configuration key. Now you must use 'pass'.
ironcamel/Dancer2-Plugin-DBIC#6 ironcamel/Dancer2-Plugin-DBIC#6

—
Reply to this email directly or view it on GitHub #583 (comment).

Dancer::Plugin::DBIC complains about password as well.

Regards
Racke

Perl and Dancer Development

Visit our Perl::Dancer conference 2014:

http://act.perl.dance/

[racke]

xsawyerx: what about starting by putting the information into the Github Wiki. That would be easier for users to get involved?

[xsawyerx]

@racke I don't mind. I don't know if it will help more, but maybe.

[racke]

Also we won't carry around a half baken POD :-).

[xsawyerx]

+1

[xsawyerx]

Since the Migration document is already out and released, I'm closing this issue.

With any new migration documentation improvement, feel free to open a new issue or a pull request to the current document.