[IMP] doc: related fields do not support chained x2m dependencies

The behavior isn't exactly undefined: it will appear to work if the
relation refers to only 1 instance. If there are multiple it will give
results for 1 instance and ignore the others. This behavior should not
be relied upon, hence I'm documenting it as undefined. I confirmed this
with mat from the ORM team.

Even better would be to raise an error or warning if `related` is used
in this context.

closes odoo/odoo#57647

Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>
Signed-off-by: Raf Geens <raf-odoo@users.noreply.github.com>
Co-authored-by: Raf Geens <raf@odoo.com>

doc/reference/orm.rst

@@ -445,6 +445,28 @@ stored::
 
     nickname = fields.Char(related='user_id.partner_id.name', store=True)
 
+.. warning::
+
+    You cannot chain :class:`~odoo.fields.Many2many` or :class:`~odoo.fields.One2many` fields in ``related`` fields dependencies.
+
+    ``related`` can be used to refer to a :class:`~odoo.fields.One2many` or
+    :class:`~odoo.fields.Many2many` field on another model on the
+    condition that it's done through a ``Many2one`` relation on the current model.
+    ``One2many`` and ``Many2many`` are not supported and the results will not be
+    aggregated correctly::
+
+      m2o_id = fields.Many2one()
+      m2m_ids = fields.Many2many()
+      o2m_ids = fields.One2many()
+
+      # Supported
+      d_ids = fields.Many2many(related="m2o_id.m2m_ids")
+      e_ids = fields.One2many(related="m2o_id.o2m_ids")
+
+      # Won't work: use a custom Many2many computed field instead
+      f_ids = fields.Many2many(related="m2m_ids.m2m_ids")
+      g_ids = fields.One2many(related="o2m_ids.o2m_ids")
+
 onchange: updating UI on the fly
 --------------------------------