Document and warn against ambiguous behaviour, closes #1175

CHANGELOG.md

@@ -12,7 +12,7 @@
 
  * Add `Plug.Conn.get_session/3` for default value
  * Allow `Plug.SSL.configure/1` to accept all :ssl options
- * Optimize query decoding by 15% to 45% - this removes the previously deprecated `:limit` MFA and `:include_unnamed_parts_at` from MULTIPART
+ * Optimize query decoding by 15% to 45% - this removes the previously deprecated `:limit` MFA and `:include_unnamed_parts_at` from MULTIPART. This may be backwards incompatible for applications that were relying on ambiguous arguments, such as `user[][key]=1&user[][key]=2`, which has unspecified parsing behaviour
 
 ## v1.14.2 (2023-03-23)
 

lib/plug/conn/query.ex

@@ -24,6 +24,20 @@ defmodule Plug.Conn.Query do
  iex> decode("foo[]=bar&foo[]=baz")["foo"]
  ["bar", "baz"]
 
+ > #### Nesting inside lists {: .error}
+ >
+ > Nesting inside lists is ambiguous and unspecified behaviour.
+ > Therefore, you should not rely on the decoding behaviour of
+ > `user[][foo]=1&user[][bar]=2`.
+ >
+ > As an alternative, you can explicitly specify the keys:
+ >
+ > # If foo and bar belong to the same entry
+ > user[0][foo]=1&user[0][bar]=2
+ >
+ > # If foo and bar are different entries
+ > user[0][foo]=1&user[1][bar]=2
+
  Keys without values are treated as empty strings,
  according to https://url.spec.whatwg.org/#application/x-www-form-urlencoded: