Documentation on ordering by ForeignKey fields is misleading

[David Wolever]

From the most recent documentation (​https://docs.djangoproject.com/en/dev/ref/models/querysets/#order-by):

If you try to order by a field that is a relation to another model, Django will use the default ordering on the related model (or order by the related model’s primary key if there is no Meta.ordering specified. For example:

Entry.objects.order_by('blog')

...is identical to:

Entry.objects.order_by('blogid')

...since the Blog model has no default ordering specified.

But this is misleading, and should probably show ordering by the related model's ordering.

A quick example that might be more instructive::

class WidgetType(Model):
    id = AutoField(primary_key=True)
    label = CharField(max_length=16)
    class Meta:
        ordering = ["label"]

class Widget(Model):
    type = ForeignKey(WidgetType)

Trying to order Widget by type will produce:

>>> print Widget.objects.all().order_by("type").query
SELECT "django_testproj_widget"."id", "django_testproj_widget"."type_id"
FROM "django_testproj_widget"
INNER JOIN "django_testproj_widgettype" ON ( "django_testproj_widget"."type_id" = "django_testproj_widgettype"."id" )
ORDER BY "django_testproj_widgettype"."label" ASC

Edit I can't read and totally missed the "or order by the related model’s primary key if there is no Meta.ordering specified" each time I read the documentation. I'll leave the ticket standing as I'm probably not the only one to hit this?

[Tim Graham]

Does the attached patch add clarity?

[Tim Graham <timograham@…>]

In 11b7680d0e640a7d4b1c942f74e9197b6ec924b1:

Fixed #23774 -- Clarified QuerySet.order_by() and related models.

[Tim Graham <timograham@…>]

In 3e0d7de8a6380c5747717cf32166864a22f258d5:

[1.7.x] Fixed #23774 -- Clarified QuerySet.order_by() and related models.

Backport of 11b7680d0e from master

[Tim Graham <timograham@…>]

In b078ccf8bfcd105873f13141403a6057e430463d:

[1.6.x] Fixed #23774 -- Clarified QuerySet.order_by() and related models.

Backport of 11b7680d0e from master