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
27617	Add contributor facing documentation for the ORM	Mads Jensen	nobody	"Overall, Django's documentation is quite good for the average user, and it also covers topics on how to write custom aggregate-functions and expressions, custom lookups and more. However, documentation on how the ORM works internally is mostly something that can be achieved through talks from YouTube, and from reading the code (albeit, there are some comments, and IDE tools letting you jump between symbols and methods do help) this takes time.

Something more elaborate on the compilers would be nice (`SQLInsertCompiler`, `SQLDeleteCompiler`, `SQLAggregateCompiler`, `SQLDeleteCompiler`, `SQLCompiler`), and structures such as `PathInfo` are missing, the different methods in Query, and how Query in the `django.db.models.models` and `django.db.models.sql.query`, as well as the chain of calls that are called to generate and optimize the code/query.  The structure of a backend and what files that are necessary is also a bit absent.  It's a bit tricky to see where this would fit into the current documentation structure, but it would augment Django a lot. In https://docs.djangoproject.com/en/dev/howto/custom-lookups/ there's a comment about the compiler.

SQLalchemy outlines the structure of its architecture in a chapter in Architecture of Open Source Applications: http://aosabook.org/en/sqlalchemy.html My requests aims at providing a bit of this in some form.

Talks on YouTube that were helpful in getting some idea on how the ORM works. Since the ORM was built for relational databases, this is also the scope of this documentation request.

1. https://www.youtube.com/watch?v=CGF-0csOjPwa
2. https://opbeat.com/community/posts/expressions-by-josh-smeaton/
3. https://www.youtube.com/watch?v=OCq2eUmrCfI"	New feature	new	Documentation	1.10	Normal		documentation internals	Clifford Gama	Accepted	0	0	0	0	0	0