2 files changed, 21 insertions, 1 deletions
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 4e8bf266b5..9e0eb3ba65 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -1202,6 +1202,8 @@ calling the appropriate methods on the wrapped expression.
         :meth:`~django.db.models.query.QuerySet.reverse()` is called on a
         queryset.
 
+.. _writing-your-own-query-expressions:
+
 Writing your own Query Expressions
 ----------------------------------
 
@@ -1262,7 +1264,7 @@ Next, we write the method responsible for generating the SQL::
             sql_params.extend(params)
         template = template or self.template
         data = {"expressions": ",".join(sql_expressions)}
-        return template % data, sql_params
+        return template % data, tuple(sql_params)
 
 
     def as_oracle(self, compiler, connection):
diff --git a/docs/releases/6.0.txt b/docs/releases/6.0.txt
index 1e45fe9aec..828e2d0354 100644
--- a/docs/releases/6.0.txt
+++ b/docs/releases/6.0.txt
@@ -427,6 +427,24 @@ Email
   significantly, closely examine any custom subclasses that rely on overriding
   undocumented, internal underscore methods.
 
+Custom ORM expressions should return params as a tuple
+------------------------------------------------------
+
+Prior to Django 6.0, :doc:`custom lookups </howto/custom-lookups>` and
+:ref:`custom expressions <writing-your-own-query-expressions>` implementing the
+``as_sql()`` method (and its supporting methods ``process_lhs()`` and
+``process_rhs()``) were allowed to return a sequence of params in either a list
+or a tuple. To address the interoperability problems that resulted, the second
+return element of the ``as_sql()`` method should now be a tuple::
+
+  def as_sql(self, compiler, connection) -> tuple[str, tuple]: ...
+
+If your custom expressions support multiple versions of Django, you should
+adjust any pre-processing of parameters to be resilient against either tuples
+or lists. For instance, prefer unpacking like this::
+
+  params = (*lhs_params, *rhs_params)
+
 Miscellaneous
 -------------