diff --git a/README.md b/README.md
index c624390ac1..badec996a7 100644
--- a/README.md
+++ b/README.md
@@ -374,6 +374,9 @@ end
 ```
 
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
+With a block, `group`, `requires` and `optional` accept an additional option `type` which can
+be either `Array` or `Hash`, and defaults to `Array`. Depending on the value, the nested
+parameters will be treated either as values of a hash or as values of hashes in an array.
 In the above example, this means `params[:media][:url]` is required along with `params[:id]`,
 and `params[:audio][:format]` is required only if `params[:audio]` is present.
 
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000000..8876dc2ccf
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,10 @@
+# Upgrading
+
+## upgrading to 0.6.2
+
+In grape <= 0.6.1, `group`, `optional` and `requires` with block accepted
+either an Array or a Hash.
+
+In grape 0.6.2, these have an additional `type` attribute which defaults
+to `Array`. This means that without a `type` attribute, these nested parameters
+will no longer accept a single hash, only an array (of hashes).