[1.0.X] Made it explicit if you accidentally override a Field from a parent model.

This was always not working reliably (model initialization and serialization
were two of the problems). Now, it's an explicit error. Also, documented.

Fixed #10252.

Backport of r9974 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@9975 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 0c87cdc9d1..469733a3b6 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -1006,3 +1006,32 @@ field or method to every class that inherits the mix-in. Try to keep your
 inheritance hierarchies as simple and straightforward as possible so that you
 won't have to struggle to work out where a particular piece of information is
 coming from.
+
+Field name "hiding" is not permitted
+-------------------------------------
+
+In normal Python class inheritance, it is permissible for a child class to
+override any attribute from the parent class. In Django, this is not permitted
+for attributes that are :class:`~django.db.models.fields.Field` instances (at
+least, not at the moment). If a base class has a field called ``author``, you
+cannot create another model field called ``author`` in any class that inherits
+from that base class.
+
+Overriding fields in a parent model leads to difficulties in areas such as
+initialising new instances (specifying which field is being intialised in
+``Model.__init__``) and serialization. These are features which normal Python
+class inheritance doesn't have to deal with in quite the same way, so the
+difference between Django model inheritance and Python class inheritance isn't
+merely arbitrary.
+
+This restriction only applies to attributes which are
+:class:`~django.db.models.fields.Field` instances. Normal Python attributes
+can be overridden if you wish. It also only applies to the name of the
+attribute as Python sees it: if you are manually specifying the database
+column name, you can have the same column name appearing in both a child and
+an ancestor model for multi-table inheritance (they are columns in two
+different database tables).
+
+Django will raise a ``FieldError`` exception if you override any model field
+in any ancestor model.
+