[1.6.x] Fixed #24041 -- Documented effect of changing a model instance's primary key.

Backport of 4ccdf6e57f49d7e981dcd88c1db65229b8b92487 from master

2 files changed, 24 insertions, 2 deletions

diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 5c11412e33..6f63884d01 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -258,8 +258,13 @@ don't need to set ``primary_key=True`` on any of your fields unless you want to
 override the default primary-key behavior. For more, see
 :ref:`automatic-primary-key-fields`.
 
-``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
-Only one primary key is allowed on an object.
+``primary_key=True`` implies :attr:`null=False <Field.null>` and
+:attr:`unique=True <Field.unique>`. Only one primary key is allowed on an
+object.
+
+The primary key field is read-only. If you change the value of the primary
+key on an existing object and then save it, a new object will be created
+alongside the old one.
 
 ``unique``
 ----------
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index fdfa8b3895..916605f6dc 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -212,6 +212,23 @@ ones:
     unless you want to override the default primary-key behavior. For more,
     see :ref:`automatic-primary-key-fields`.
 
+    The primary key field is read-only. If you change the value of the primary
+    key on an existing object and then save it, a new object will be created
+    alongside the old one. For example::
+
+        from django.db import models
+
+        class Fruit(models.Model):
+            name = models.CharField(max_length=100, primary_key=True)
+
+    .. code-block:: pycon
+
+        >>> fruit = Fruit.objects.create(name='Apple')
+        >>> fruit.name = 'Pear'
+        >>> fruit.save()
+        >>> Fruit.objects.values_list('name', flat=True)
+        ['Apple', 'Pear']
+
 :attr:`~Field.unique`
     If ``True``, this field must be unique throughout the table.