id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
34373	"Update docs on ForeignKey to suggest setting ""to"" and object before a string"	Salaah Amin		"In the documentation around model [https://docs.djangoproject.com/en/4.1/ref/models/fields/#foreignkey ForeignKeys], the documentation explains how to set `to` to a string which references a model before showing how an actual model can be referenced in the [https://docs.djangoproject.com/en/4.1/ref/models/fields/#django.db.models.ForeignKey.on_delete on_delete section].

I propose adding a section before the string version, explaining how the `ForeignKey` can be used using a reference to a model using the model class itself. This is purely to avoid defaulting to the string method which makes it easy to fall into the circular dependencies later down the line.

So in other words, rather than jumping into:

{{{#!python
class Car(models.Model):
    manufacturer = models.ForeignKey(
        'Manufacturer',
        on_delete=models.CASCADE,
    )
    # ...
}}}

It may be helpful to show the following beforehand:

{{{#!python
class Car(models.Model):
    manufacturer = models.ForeignKey(
        Manufacturer,
        on_delete=models.CASCADE,
    )
    # ...
}}}

In addition, I propose adding some additional information suggesting (if we do agree on this) that circular dependencies should be avoided, especially as it can mess up migration orders and make it difficult to squash migrations at a later stage."	Cleanup/optimization	closed	Documentation	4.1	Normal	wontfix			Unreviewed	0	0	0	0	1	0