Updated README and UPGRADING

README.md

@@ -2130,8 +2130,9 @@ curl -H "secret_PassWord: swordfish" ...
 
 The header name will have been normalized for you.
 
-- In the `header` helper names will be coerced into a capitalized kebab case.
-- In the `env` collection they appear in all uppercase, in snake case, and prefixed with 'HTTP_'.
+- In the `header` helper names will be coerced into a downcased kebab case as `secret-password` if using Rack 3.
+- In the `header` helper names will be coerced into a capitalized kebab case as `Secret-PassWord` if using Rack < 3.
+- In the `env` collection they appear in all uppercase, in snake case, and prefixed with 'HTTP_' as `HTTP_SECRET_PASSWORD`
 
 The header name will have been normalized per HTTP standards defined in [RFC2616 Section 4.2](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) regardless of what is being sent by a client.
 

UPGRADING.md

@@ -3,27 +3,30 @@ Upgrading Grape
 
 ### Upgrading to >= 1.9.0
 
-#### Response Headers
-
-As per [rack/rack#1592](https://github.com/rack/rack/issues/1592) Rack 3.0 is enforcing the HTTP/2 semantics, and thus treats all headers as lowercase. Starting with Grape 1.9.0, the following headers are now lowercase:
-
-* `allow`
-* `cache-control`
-* `content-length`
-* `content-type`
-* `location`
-* `transfer-encoding`
-* `x-cascade`
-
-For Rack < 3 the following response headers are returned using HTTP/1 semantics, like so:
-
-* `Allow`
-* `Cache-Control`
-* `Content-Length`
-* `Content-Type`
-* `Location`
-* `Transfer-Encoding`
-* `X-Cascade`
+#### Headers
+
+As per [rack/rack#1592](https://github.com/rack/rack/issues/1592) Rack 3.0 is enforcing the HTTP/2 semantics, and thus treats all headers as lowercase. Starting with Grape 1.9.0, headers will be cased based on what version of Rack you are using.
+
+Given this request:
+
+```shell
+curl -H "Content-Type: application/json" -H "Secret-Password: foo" ...
+```
+
+If you are using Rack 3 in your application then the headers will be set to:
+
+```ruby
+{ "content-type" => "application/json", "secret-password" => "foo"}
+```
+
+This means if you are checking for header values in your application, you would need to change your code to use downcased keys. 
+
+```ruby
+get do
+  # This would use headers['Secret-Password'] in Rack < 3
+  error!('Unauthorized', 401) unless headers['secret-password'] == 'swordfish'
+end
+```
 
 See [#2355](https://github.com/ruby-grape/grape/pull/2355) for more information.