Add explicit note about @hybrid_property mutators re: method name

Fixes: #4332
Change-Id: I7c52140d3a3055a71b192fea020c795a57356d90

diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index d70c6db52f69032d3d60313dc300da2d9d4e90df..e2df22953739176f8c9b0d17cb651f5b61f00ce2 100644 (file)
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -374,6 +374,33 @@ hybrid in-place, interfering with the definition on the superclass.
    :attr:`.hybrid_property.overrides` may be necessary to avoid name
    conflicts with :class:`.QueryableAttribute` in some cases.
 
+.. note:: This change in ``@hybrid_property`` implies that when adding setters and
+   other state to a ``@hybrid_property``, the **methods must retain the name
+   of the original hybrid**, else the new hybrid with the additional state will
+   be present on the class as the non-matching name.  This is the same behavior
+   as that of the ``@property`` construct that is part of standard Python::
+
+        class FirstNameOnly(Base):
+            @hybrid_property
+            def name(self):
+                return self.first_name
+
+            # WRONG - will raise AttributeError: can't set attribute when
+            # assigning to .name
+            @name.setter
+            def _set_name(self, value):
+                self.first_name = value
+
+        class FirstNameOnly(Base):
+            @hybrid_property
+            def name(self):
+                return self.first_name
+
+            # CORRECT - note regular Python @property works the same way
+            @name.setter
+            def name(self, value):
+                self.first_name = value
+
 :ticket:`3911`
 
 :ticket:`3912`