model-api documentation should note model inheritance should not be used

[calvins]

I was told in the IRC channel that model inheritance is known to be broken at the moment and is not supposed to work.

The primary documentation page, ​Django | Model reference | Django Documentation, does not note that it should not be used.

In the "basics" bullet points of that page, the first point is: "Each model is a Python class that subclasses django.db.models.Model." That would be the logical point to put a boldface warning that you can't extend any model types that extend models.Model and friends. You might want to link to ​IRCFAQ How do I extend a model? and/or ​Model Inheritance.

It would be nice too if django gave a warning (perhaps only at verbosity=2) when the user does this and tries to use either loaddata or dumpdata (or any other db-related manage.py functions), since a user that knows the model-api reasonably well might not check the documentation until they've spent a long time trying to figure out why some of their objects don't get serialized at all using dumpdata. In my case, I had a trivial sub-type of a model that I had defined (literally "class Archived_Item(Item): pass"), and spent a long time trying to figure out why just 1 object was not serialized using dumpdata, which caused problems when loaddata is run (where I originally thought the problem was).

[Malcolm Tredinnick]

Not worth it at the moment. It takes 30 seconds to search on Google and discover model inheritance doesn't work and by the time the next release is out (in fact, well before that), model inheritance will be part of trunk. This just isn't a common enough use-case to justify the time putting in extra code and maintaining it on a temporary basis.