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=432e3d08401e0add95aeac4451c1ae339dd9782d;hp=094191d28c42584efee5508128d6fde9c6ad261f;hb=5e7e6b272a9e1b8bf1c401dd3a607fc851c43cc7;hpb=e5ac67e5d706bf2e4a4c33537479f70c409a6e4e

diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod
index 094191d..432e3d0 100644
--- a/lib/Catalyst/Upgrading.pod
+++ b/lib/Catalyst/Upgrading.pod
@@ -4,6 +4,58 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
 
 =head1 Upgrading to Catalyst 5.90100
 
+We changed the way the middleware stash works so that it no longer localizes
+the PSGI env hashref.  This was done to fix bugs where people set PSGI ENV hash
+keys and found them to dissappear in certain cases.  It also means that now if
+a sub applications sets stash variables, that stash will now bubble up to the
+parent application.  This may be a breaking change for you since previous
+versions of this code did not allow that.  A workaround is to explicitly delete
+stash keys in your sub application before returning control to the parent
+application.
+
+=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($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 string form of the first argument:
+
+    $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