Ticket #17436: patch_17436.diff

docs/ref/models/instances.txt

@@ -25 +25 @@
 model. Note that instantiating a model in no way touches your database; for
 that, you need to :meth:`~Model.save()`.
 
+.. note::
+    You may be tempted to customize the model and override the ``__init__``
+    method. However, take care not to change the calling signature, as any
+    change may prevent the model instance from being saved. Try using one of
+    alternative approaches instead. First of these involves a classmethod on
+    the model class::
+
+        class Book(models.Model):
+            title = models.CharField(max_length=100)
+
+            @classmethod
+            def create(cls, title):
+                book = cls(title=title)
+                # do something with the book
+                return book
+
+    You can then use the method as follows::
+
+        book = Book.create("Pride and Prejudice")
+
+    Another (and usually preferred) way is to define a method on a custom
+    manager::
+
+        class BookManager(models.Manager):
+            def create_book(title):
+                book = self.create(title=title)
+                # do something with the book
+                return book
+
+        class Book(models.Model):
+            title = models.CharField(max_length=100)
+
+            objects = BookManager()
+
+    And use it like this::
+
+        book = Book.objects.create_book("Pride and Prejudice")
+
 .. _validating-objects:
 
 Validating objects