X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=ac230c16baaa6758f5f0080d2666caa8a14ec750;hp=75a74f76adb01eb953baef17d4e27317f3d52954;hb=02336198551ec2d7edfa74911919b8804bfc69c8;hpb=a791afa956ab3567617c2cdb3065a481b5a7b7f2

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index 75a74f7..ac230c1 100644
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -2,6 +2,61 @@
 
 Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
 
+=head1 Upgrading to Catalyst 5.90097
+
+In older versions of Catalyst one could construct a L<URI> with a fragment (such as
+https://localhost/foo/bar#fragment) by using a '#' in the path or final argument, for
+example:
+
+    $c->uri_for('/mypath#fragment');
+
+or:
+
+    $c->uri_for($action, 'foo#fragment');
+
+This behavior was never documented and would break if using the Unicode plugin, or when
+adding a query to the arguments:
+
+    $c->uri_for($action, 'foo#fragment', +{ a=>1, b=>2});
+
+would define a fragment like "#fragment?a=1&b=2".
+
+When we introduced UTF-8 encoding by default in Catalyst 5.9008x this side effect behavior
+was broken since we started encoding the '#' when it was part of the URI path.
+
+In version 5.90095 and 5.90096 we attempted to fix this, but all we managed to do was break
+people with URIs that included '#' as part of the path data, when it was not expected to
+be a fragment delimiter.
+
+In general L<Catalyst> prefers an explicit specification rather than relying on side effects
+or domain specific mini languages.  As a result we are now defining how to set a fragment
+for a URI via ->uri_for:
+
+    $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment);
+
+If you are relying on the previous side effect behavior your URLs will now encode the '#'
+delimiter, which is going to be a breaking change for you.  You need to alter your code
+to match the new specification or modify uri_for for your local case.  Patches to solve
+this are very welcomed, as long as they don't break existing test cases.
+
+B<NOTE> If you are using the alternative:
+
+    $c->uri_for('/foo/bar#baz')
+
+construction, we do not attempt to encode this and it will make a URL with a
+fragment of 'baz'.
+
+
+=head1 Upgrading to Catalyst 5.90095
+
+The method C<last_error> in L</Catalyst> was actually returning the first error.  This has
+been fixed but there is a small chance it could be a breaking issue for you.  If this gives
+you trouble changing to C<shift_errors> is the easiest workaround (although that does
+modify the error stack so if you are relying on that not being changed you should try something
+like @{$c->errors}[-1] instead.  Since this method is relatively new and the cases when the
+error stack actually has more than one error in it, we feel the exposure is very low, but bug
+reports are very welcomed.
+
 =head1 Upgrading to Catalyst 5.90090
 
 L<Catalyst::Utils> has a new method 'inject_component' which works the same as the method of
@@ -49,6 +104,47 @@ and 'stats_class_traits', so you use like this (note this value is an ArrayRef)
 traits for Engine, since that class does a lot less nowadays, and dispatcher.  If you
 used those and can share a use case, we'd be likely to support them.
 
+Lastly, we have some of the feature from L<CatalystX::ComponentsFromConfig> in
+core.  This should mostly work the same way in core, except for now the
+core version does not create an automatic base wrapper class for your configured
+components (it requires these to be catalyst components and injects them directly.
+So if you make heavy use of custom base classes in L<CatalystX::ComponentsFromConfig>
+you might need a bit of work to use the core version (although there is no reason
+to stop using L<CatalystX::ComponentsFromConfig> since it should continue to work
+fine and we'd consider issues with it to be bugs).  Here's one way to map from
+L<CatalystX::ComponentsFromConfig> to core:
+
+In L<CatalystX::ComponentsFromConfig>:
+
+    MyApp->config(
+      'Model::MyClass' => {
+          class => 'MyClass',
+          args => { %args },
+
+      });
+
+and now in core:
+
+    MyApp->config(
+      inject_components => {
+        'Model::MyClass' => { from_component => 'My::Class' },
+      },
+      'Model::MyClass' => {
+        %args
+      },
+    );
+
+Although the cored behavior requires more code, its better separates concerns
+as well as plays more into core Catalyst expections of how configuration shoul
+look.
+
+Also we added a new develop console mode only warning when you call a component
+with arguments that don't expect or do anything meaningful with those args.  Its
+possible if you are logging debug mode in production (please don't...) this 
+could add verbosity to those logs if you also happen to be calling for components
+and passing pointless arguments.  We added this warning to help people not make this
+error and to better understand the component resolution flow.
+
 =head1 Upgrading to Catalyst 5.90085
 
 In this version of Catalyst we made a small change to Chained Dispatching so