[DOC] api: warn about onchange pitfalls

closes odoo/odoo#37836

X-original-commit: a8454381ad2151136ee2a49665f69a12b8dc7daf
Signed-off-by: Adrian Torres (adt) <adt@odoo.com>

1 files changed, 10 insertions, 0 deletions

diff --git a/odoo/api.py b/odoo/api.py
index 4015156f1a3..8965fa6e886 100644
--- a/odoo/api.py
+++ b/odoo/api.py
@@ -177,6 +177,16 @@ def onchange(*args):
             If the type is set to notification, the warning will be displayed in a notification.
             Otherwise it will be displayed in a dialog as default.
 
+        .. danger::
+
+            Since ``@onchange`` returns a recordset of pseudo-records,
+            calling any one of the CRUD methods
+            (:meth:`create`, :meth:`read`, :meth:`write`, :meth:`unlink`)
+            on the aforementioned recordset is undefined behaviour,
+            as they potentially do not exist in the database yet.
+
+            Instead, simply set the record's field like shown in the example
+            above or call the :meth:`update` method.
 
         .. warning::