[2.0.x] Fixed #29126 -- Doc'd the behavior of QuerySet.update_or_create() with manually specified pks.

Backport of e917ea6bec from master

docs/ref/models/querysets.txt

@@ -1974,6 +1974,10 @@ As described above in :meth:`get_or_create`, this method is prone to a
 race-condition which can result in multiple rows being inserted simultaneously
 if uniqueness is not enforced at the database level.
 
+Like :meth:`get_or_create` and :meth:`create`, if you're using manually
+specified primary keys and an object needs to be created but the key already
+exists in the database, an :exc:`~django.db.IntegrityError` is raised.
+
 .. versionchanged:: 1.11
 
     Added support for callable values in ``defaults``.

tests/get_or_create/tests.py

@@ -444,6 +444,19 @@ class UpdateOrCreateTests(TestCase):
         self.assertEqual(obj.last_name, 'NotHarrison')
 
 
+class UpdateOrCreateTestsWithManualPKs(TestCase):
+
+    def test_create_with_duplicate_primary_key(self):
+        """
+        If an existing primary key is specified with different values for other
+        fields, then IntegrityError is raised and data isn't updated.
+        """
+        ManualPrimaryKeyTest.objects.create(id=1, data='Original')
+        with self.assertRaises(IntegrityError):
+            ManualPrimaryKeyTest.objects.update_or_create(id=1, data='Different')
+        self.assertEqual(ManualPrimaryKeyTest.objects.get(id=1).data, 'Original')
+
+
 class UpdateOrCreateTransactionTests(TransactionTestCase):
     available_apps = ['get_or_create']