[1.5.x] Fixed #17528 -- Documented that add() and remove() with a many-to-many relationship do not call Model.save()

Backport of 3cdeb572d7 from master

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt
index c923961a19..c693f5fd9a 100644
--- a/docs/ref/models/relations.txt
+++ b/docs/ref/models/relations.txt
@@ -44,6 +44,14 @@ Related objects reference
             >>> e = Entry.objects.get(id=234)
             >>> b.entry_set.add(e) # Associates Entry e with Blog b.
 
+        In the example above, ``e.save()`` is called to perform the update.
+        Using ``add()`` with a many-to-many relationship, however, will not
+        call any ``save()`` methods, but rather create the relationships
+        using :meth:`QuerySet.bulk_create()
+        <django.db.models.query.QuerySet.bulk_create>`. If you need to execute
+        some custom logic when a relationship is created, listen to the
+        :data:`~django.db.models.signals.m2m_changed` signal.
+
     .. method:: create(**kwargs)
 
         Creates a new object, saves it and puts it in the related object set.
@@ -82,6 +90,14 @@ Related objects reference
             >>> e = Entry.objects.get(id=234)
             >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
 
+        Similar to :meth:`add()`, ``e.save()`` is called in the example above
+        to perform the update. Using ``remove()`` with a many-to-many
+        relationship, however, will delete the relationships using
+        :meth:`QuerySet.delete()<django.db.models.query.QuerySet.delete>` which
+        means no model ``save()`` methods are called; listen to the
+        :data:`~django.db.models.signals.m2m_changed` signal if you wish to
+        execute custom code when a relationship is deleted.
+
         For :class:`~django.db.models.ForeignKey` objects, this method only
         exists if ``null=True``. If the related field can't be set to ``None``
         (``NULL``), then an object can't be removed from a relation without